com.google.android.gms.auth.api.credentials

Provides facilities to retrieve and save app login credentials.

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

1. 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.
2. If no retained user is found, then configure and instantiate a 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.
3. Once connected, create a 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();

4. Call 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.
5. If the request is successful (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.
6. 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 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.

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

     • If the result code is 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.
     • If user cancels the resolution intent, the result code will be Activity.RESULT_CANCELED.
     • If user clicks on "add account" button, the result code will be CredentialsApi.ACTIVITY_RESULT_ADD_ACCOUNT.
     • If no hints are available, the result code will be 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:

1. The user has a single credential saved for the app/
2. The user has auto sign-in enabled in their settings/
3. The app calls request() immediately in a login activity, and uses the result directly to log in/

Calling 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:

1. Enabling the save confirmation dialog for all platforms by using forceEnableSaveDialog():

   CredentialsOptions options =
        new CredentialsOptions.Builder().forceEnableSaveDialog().build();
    return new GoogleApiClient.Builder(this)
        .addApi(Auth.CREDENTIALS_API, options)
        .enableAutoManage(this, this)
        .build();
    

2. 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">
   
        <!-- ... -->