The Smart Lock for Passwords and Connected Accounts API facilitates the saving and retrieval of credentials for your app and associated site, and also helps to expedite account creation through credential hints. Integrating with this API will simplify the sign-in experience for users moving between devices where they are signed in to their Google account.
For example, a user may have an account on a website and have saved the credential for this account in Chrome. A new Android app is released for this service to provide a better mobile experience, and users are encouraged to download the app when they visit the site from mobile Chrome. This API allows the app to retrieve the saved password that was used in Chrome, providing a seamless login experience for the user without the need to manually enter credentials.
The API is activated on a
instance by adding
to the set of requested APIs. An account must not be set on the client instance,
either by calling
useDefaultAccount. Once the client is connected, credentials can be retrieved by
Auth.CredentialsApi.request(), and credentials can be saved for future retrieval
Auth.CredentialsApi.save(). Both password-based and Identity Provider (IDP, like
Google Sign-In) credentials are supported.
The recommended process for retrieving credentials using this API is as follows:
- When the application starts, check to see whether you already have access to a signed-in user. Most apps will persist the signed-in user information after the user successfully authenticates. If the app already has a signed-in user, then you do not need to use the credentials API.
- If no retained user is found, then configure and instantiate a
GoogleApiClientinstance with access to the credentials API, and connect it as normal. This instance should be separate from any instance that your application normally uses for accessing authenticated APIs — a client should be created for the purposes of acquiring a credential, then a separate client created to access APIs if the credential returned is for a Google user.
- Once connected, create a
builder, describing the methods of authentication that your app supports. For example, for an app which supports password authentication and Google Sign-In:
CredentialRequest request = new CredentialRequest.Builder() .setAccountTypes(IdentityProviders.GOOGLE) .setSupportsPasswordLogin(true) .build();
CredentialRequestinstance. This will result in an asynchronous request for any known credentials, the result of which will be signalled via a
- If the request is successful (
result.getStatus().isSuccess()is true), a stored
Credentialis available, via
getCredential(). Password-based credentials have an empty
account type, while IDP-based credentials will have the account type set by the save operation which stored it. The app should then perform any necessary authentication step for the returned credential at this point.
- If the request is unsuccessful (
result.getStatus().isSuccess()is false), this will either be because user input is required (
result.getStatus().hasResolution()is true) or there are no known credentials for this app (
result.getStatus().hasResolution()is false). Where user input is required, there are two possible reasons:
- At least one credential is known for this app, but user input is required to
release it to the app. This occurs most frequently when the user has disabled auto
sign-in or more than one account is known and the user must choose which
account they would like to use. Alternatively, the user may have to input some
additional information (e.g. a pin-code or password) to retrieve the password.
This case is indicated by
RESOLUTION_REQUIRED). The app must decide whether to immediately fire the intent to retrieve the credential (returned via
onActivityResult), or wait for some other user action (for instance, clicking a generic "sign in" button on the app's welcome screen activity).
If the resolution intent is successful (indicated by result code
onActivityResult), then the credential will be stored in the extra data intent returned to
onActivityResultunder the key
onActivityResultwill either return result code
CredentialsApi.ACTIVITY_RESULT_ADD_ACCOUNT, which means the user has cancelled the resolution intent, or user has clicked on the "add button" button, respectively.
- No credentials are known for this user, but a credential hint can be
supplied. Credential hints provide seed information for a new account sign-up flow,
based on information that the user has used for other accounts - it is common for
users to use the same email address or username across multiple apps and sites, for
instance. Using a credential hint should reduce the amount of typing required to
create a new account, increasing the account creation rate for your app.
This case is indicated by
SIGN_IN_REQUIRED). Firing the resolution intent can result in several possible cases, which can be handled by
onActivityResultand identified by the result code.
- If the result code is
Credentialwill be returned in the extra intent of
onActivityResultunder the key
Credential.EXTRA_KEY. The credential will contain at least a user id, and may also contain a display name, profile picture URL, and verifying id tokens, if available.
- If user cancels the resolution intent, the result code will be
- If user clicks on "add account" button, the result code will be
- If no hints are available, the result code will be
- If the result code is
- At least one credential is known for this app, but user input is required to release it to the app. This occurs most frequently when the user has disabled auto sign-in or more than one account is known and the user must choose which account they would like to use. Alternatively, the user may have to input some additional information (e.g. a pin-code or password) to retrieve the password.
When a credential is successfully used by your app to sign in to an existing account or
create a new account, it is recommended to call
save() with this credential. The credential will then be retained for any future
request(). Saving a credential may fail with a resolution intent, indicating
that user input is required in order to safely persist the credential. It is therefore
required for apps to invoke this intent, when returned, to ensure the credential will be
correctly returned on future calls to
If the app discovers that a credential returned by the API is invalid, a call to
delete() should be made. This will remove this credential from the store.
When a user logs out of the app, it is recommended to call
disableAutoSignIn() in order to prevent a possible login loop in the app. This
login loop can occur when all the following are true:
- The user has a single credential saved for the app/
- The user has auto sign-in enabled in their settings/
- The app calls
request()immediately in a login activity, and uses the result directly to log in/
disableAutoSignIn()temporarily disables auto sign-in for the app on the current device only, which will give the user the opportunity to explicitly choose whether to log back in with the same credential, or cancel and log in with a new account.
Targeting Android O and above
When the current device is running Android O or above a credential
save request that requires showing a save confirmation may be cancelled in favor
of the Autofill save dialog. Please note that credential data saved via Autofill with
Google is bi-directionally shared with the Smart Lock for Passwords API. To prefer showing
the Smart Lock for Passwords save dialog:
- Enabling the save confirmation dialog for all platforms by using
CredentialsOptions options = new CredentialsOptions.Builder().forceEnableSaveDialog().build(); return new GoogleApiClient.Builder(this) .addApi(Auth.CREDENTIALS_API, options) .enableAutoManage(this, this) .build();
- Suppress the Autofill save dialog by marking the root view associated with the login
fields as not important for Autofill:
<!-- Mark the root view with android:importantForAutofill="noExcludeDescendants" --> <LinearLayout android:importantForAutofill="noExcludeDescendants" android:layout_width="match_parent" android:layout_height="wrap_content" android:orientation="vertical"> <!-- ... -->
|CredentialPickerConfig.Prompt||The set of supported prompts to display at the top of a credential hint picker.|
|CredentialRequestResult||Result returned from a request for a credential.|
|CredentialsApi||Entry point for requesting a credential and indicating whether sign-in was successful using the credential.|
|Credential||A credential that can be used to authenticate a user, with additional user information used to distinguish this credential from other available credentials.|
|CredentialPickerConfig||Configuration for credential picker.|
|CredentialRequest||Parameters for requesting a
|CredentialRequestResponse||Result returned from a request for a credential.|
|Credentials||Entry point for the Credentials API.|
|CredentialsClient||Entry point for requesting a credential and indicating whether sign-in was successful using the credential.|
|CredentialsOptions||Optional configuration for the Credentials API.|
|HintRequest||Parameters for requesting the display of the hint
|IdentityProviders||Identity provider constants for use with
|IdToken||A token that is signed by an