Use shared web credentials to create a seamless experience for the user.
There are a wide range of common situations where you may want to use shared web credentials. This article covers four:
Logging in to a remote server
Creating a user account in the app
Changing a user’s password
Deleting a user’s account
Logging In to a Remote Server
Typically, when an app needs to log in to a remote service, you start by checking for the user’s credentials in the iOS keychain. If you have current credentials for the user, you can log them in directly. If not, prompt the users for their user name and password, and then try to log them in. You will also want to save their credentials after the login is successful. This workflow is shown in Figure 1.
When using shared web credentials, you add two steps to this procedure. As before, you start by checking if the user’s credentials are stored in the keychain. If you cannot find the user’s credentials, you check for shared web credentials. If you still cannot find any credentials, or if the user declines to use the shared credentials, you must prompt the user for her name and password. Try to log the user in, and if the login is successful, save the credentials to both the keychain and the shared web credentials. This ensures that the user has access to the credentials in Safari as well as within your app. This workflow is shown in Figure 2.
Do not use the shared web credentials as your primary storage for secure user credentials. Instead, save the user’s credentials in the keychain, and only use the shared web credentials when you can’t find the login credentials in the keychain.
To read the user’s credentials from the shared web credentials, use the
Sec function as shown in Listing 1.
Creating a User Account in the App
If the user can create new accounts in your app, you should save the user name and password to the shared web credentials. In this way, the user can easily access the account from Safari, as well as from within your app. You can save the user’s name and password to the shared web credentials using the
Sec function as shown.
If there are no existing credentials for this user name and domain, this method completes without prompting the user for permission.
Changing a User’s Password
If the user changes her password in the app, you must update both the credentials stored in the keychain and in the shared web credentials. You can change a password using the
Sec function. This is exactly the same procedure used when creating a new user account (see Listing 2). However, if credentials already exist for the given user name and domain, this method prompts the user for permission before making the change. The user can cancel this change.
Deleting a User’s Account
If the user deletes her account, you should remove the credentials from both the keychain and the shared web credentials. You can remove the credentials for a given domain and user name by calling the
Sec function and passing
NULL for the password.
The system prompts the user for permission before deleting their user name and password from the shared web credentials. Users can cancel this change.