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
.
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.
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 | |
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 . |