package

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

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

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.

## Interfaces

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.

## Classes

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 `Auth.CredentialsApi.request()`.
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`.