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 in 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 GoogleApiClient
instance by adding Auth.CREDENTIALS_API
to the set of requested APIs. An account must not be set on the
client instance, either by calling setAccountName
or useDefaultAccount
. Once the client is connected, credentials can be retrieved by calling Auth.CredentialsApi.request()
, and credentials can be saved for future retrieval by calling
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:
GoogleApiClient
instance 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.
CredentialRequest
using the 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();
Auth.CredentialsApi.request
with the CredentialRequest
instance. This will result
in an asynchronous request for any known credentials, the result of which will be signalled
via a PendingResult
for a CredentialRequestResult
.
result.getStatus().isSuccess()
is true), a stored
Credential
is 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.
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:
This case is indicated by result.getStatus().getStatusCode()
returning
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 Activity.RESULT_OK
passed to onActivityResult
), then the credential will be stored in the extra data intent
returned to onActivityResult
under the key Credential.EXTRA_KEY
.
Otherwise, onActivityResult
will either return result code Activity.RESULT_CANCELED
or CredentialsApi.ACTIVITY_RESULT_ADD_ACCOUNT
, which means the user has cancelled the
resolution intent, or user has clicked on the "add button" button, respectively.
This case is indicated by result.getStatus().getStatusCode()
returning
SIGN_IN_REQUIRED
). Firing
the resolution intent can result in several possible cases, which can be handled by
onActivityResult
and identified by the result code.
Activity.RESULT_OK
, Credential
will be returned in the
extra intent of onActivityResult
under 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.
Activity.RESULT_CANCELED
.
CredentialsApi.ACTIVITY_RESULT_ADD_ACCOUNT
.
CredentialsApi.ACTIVITY_RESULT_NO_HINTS_AVAILABLE
.
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 calls to 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 request()
.
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:
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.
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:
forceEnableSaveDialog()
:
CredentialsOptions options =
new CredentialsOptions.Builder().forceEnableSaveDialog().build();
return new GoogleApiClient.Builder(this)
.addApi(Auth.CREDENTIALS_API, options)
.enableAutoManage(this, this)
.build();
<!-- 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">
<!-- ... -->
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. |
Credential.Builder | |
CredentialPickerConfig | Configuration for credential picker. |
CredentialPickerConfig.Builder | Builder for CredentialPickerConfig . |
CredentialRequest | Parameters for requesting a Credential , via request(com.google.android.gms.common.api.GoogleApiClient, CredentialRequest) . |
CredentialRequest.Builder | |
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. |
CredentialsOptions.Builder | Builder for CredentialsOptions . |
HintRequest | Parameters for requesting the display of the hint picker, via getHintPickerIntent() . |
HintRequest.Builder | |
IdentityProviders | Identity provider constants for use with CredentialRequest.Builder.setAccountTypes() . |
IdToken | A token that is signed by an Authenticator to confirm that the account specified in the
idToken is a valid account of accountType . |