Added in API level 34

CredentialManager


public final class CredentialManager
extends Object

java.lang.Object
   ↳ android.credentials.CredentialManager


Manages user authentication flows.

Note that an application should call the Jetpack CredentialManager apis instead of directly calling these framework apis.

The CredentialManager apis launch framework UI flows for a user to register a new credential or to consent to a saved credential from supported credential providers, which can then be used to authenticate to the app.
Requires the PackageManager#FEATURE_CREDENTIALS feature which can be detected using PackageManager.hasSystemFeature(String).

Summary

Public methods

void clearCredentialState(ClearCredentialStateRequest request, CancellationSignal cancellationSignal, Executor executor, OutcomeReceiver<VoidClearCredentialStateException> callback)

Clears the current user credential state from all credential providers.

void createCredential(Context context, CreateCredentialRequest request, CancellationSignal cancellationSignal, Executor executor, OutcomeReceiver<CreateCredentialResponseCreateCredentialException> callback)

Launches the necessary flows to register an app credential for the user.

void getCredential(Context context, PrepareGetCredentialResponse.PendingGetCredentialHandle pendingGetCredentialHandle, CancellationSignal cancellationSignal, Executor executor, OutcomeReceiver<GetCredentialResponseGetCredentialException> callback)

Launches the remaining flows to retrieve an app credential from the user, after the completed prefetch work corresponding to the given pendingGetCredentialHandle.

void getCredential(Context context, GetCredentialRequest request, CancellationSignal cancellationSignal, Executor executor, OutcomeReceiver<GetCredentialResponseGetCredentialException> callback)

Launches the necessary flows to retrieve an app credential from the user.

boolean isEnabledCredentialProviderService(ComponentName componentName)

Returns true if the calling application provides a CredentialProviderService that is enabled for the current user, or false otherwise.

void prepareGetCredential(GetCredentialRequest request, CancellationSignal cancellationSignal, Executor executor, OutcomeReceiver<PrepareGetCredentialResponseGetCredentialException> callback)

Prepare for a get-credential operation.

void registerCredentialDescription(RegisterCredentialDescriptionRequest request)

Registers a CredentialDescription for an actively provisioned Credential a CredentialProvider has.

void unregisterCredentialDescription(UnregisterCredentialDescriptionRequest request)

Unregisters a CredentialDescription for an actively provisioned Credential that has been registered previously.

Inherited methods

Public methods

clearCredentialState

Added in API level 34
public void clearCredentialState (ClearCredentialStateRequest request, 
                CancellationSignal cancellationSignal, 
                Executor executor, 
                OutcomeReceiver<VoidClearCredentialStateException> callback)

Clears the current user credential state from all credential providers.

You should invoked this api after your user signs out of your app to notify all credential providers that any stored credential session for the given app should be cleared.

A credential provider may have stored an active credential session and use it to limit sign-in options for future get-credential calls. For example, it may prioritize the active credential over any other available credential. When your user explicitly signs out of your app and in order to get the holistic sign-in options the next time, you should call this API to let the provider clear any stored credential session.

Parameters
request ClearCredentialStateRequest: the request data This value cannot be null.

cancellationSignal CancellationSignal: an optional signal that allows for cancelling this call This value may be null.

executor Executor: the callback will take place on this Executor Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread. This value cannot be null.

callback OutcomeReceiver: the callback invoked when the request succeeds or fails This value cannot be null.

createCredential

Added in API level 34
public void createCredential (Context context, 
                CreateCredentialRequest request, 
                CancellationSignal cancellationSignal, 
                Executor executor, 
                OutcomeReceiver<CreateCredentialResponseCreateCredentialException> callback)

Launches the necessary flows to register an app credential for the user.

The execution can potentially launch UI flows to collect user consent to creating or storing the new credential, etc. Callers (e.g. browsers) may optionally set origin in CreateCredentialRequest for an app different from their own, to be able to get credentials on behalf of that app. They would need additional permission CREDENTIAL_MANAGER_SET_ORIGIN to use this functionality

Parameters
context Context: the context used to launch any UI needed; use an activity context to make sure the UI will be launched within the same task stack This value cannot be null.

request CreateCredentialRequest: the request specifying type(s) of credentials to get from the user This value cannot be null.

cancellationSignal CancellationSignal: an optional signal that allows for cancelling this call This value may be null.

executor Executor: the callback will take place on this Executor Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread. This value cannot be null.

callback OutcomeReceiver: the callback invoked when the request succeeds or fails This value cannot be null.

getCredential

Added in API level 34
public void getCredential (Context context, 
                PrepareGetCredentialResponse.PendingGetCredentialHandle pendingGetCredentialHandle, 
                CancellationSignal cancellationSignal, 
                Executor executor, 
                OutcomeReceiver<GetCredentialResponseGetCredentialException> callback)

Launches the remaining flows to retrieve an app credential from the user, after the completed prefetch work corresponding to the given pendingGetCredentialHandle.

The execution can potentially launch UI flows to collect user consent to using a credential, display a picker when multiple credentials exist, etc.

Use this API to complete the full credential retrieval operation after you initiated a request through the prepareGetCredential(android.credentials.GetCredentialRequest, android.os.CancellationSignal, java.util.concurrent.Executor, android.os.OutcomeReceiver) API.

Parameters
context Context: the context used to launch any UI needed; use an activity context to make sure the UI will be launched within the same task stack This value cannot be null.

pendingGetCredentialHandle PrepareGetCredentialResponse.PendingGetCredentialHandle: the handle representing the pending operation to resume This value cannot be null.

cancellationSignal CancellationSignal: an optional signal that allows for cancelling this call This value may be null.

executor Executor: the callback will take place on this Executor Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread. This value cannot be null.

callback OutcomeReceiver: the callback invoked when the request succeeds or fails This value cannot be null.

getCredential

Added in API level 34
public void getCredential (Context context, 
                GetCredentialRequest request, 
                CancellationSignal cancellationSignal, 
                Executor executor, 
                OutcomeReceiver<GetCredentialResponseGetCredentialException> callback)

Launches the necessary flows to retrieve an app credential from the user.

The execution can potentially launch UI flows to collect user consent to using a credential, display a picker when multiple credentials exist, etc. Callers (e.g. browsers) may optionally set origin in GetCredentialRequest for an app different from their own, to be able to get credentials on behalf of that app. They would need additional permission CREDENTIAL_MANAGER_SET_ORIGIN to use this functionality

Parameters
context Context: the context used to launch any UI needed; use an activity context to make sure the UI will be launched within the same task stack This value cannot be null.

request GetCredentialRequest: the request specifying type(s) of credentials to get from the user This value cannot be null.

cancellationSignal CancellationSignal: an optional signal that allows for cancelling this call This value may be null.

executor Executor: the callback will take place on this Executor Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread. This value cannot be null.

callback OutcomeReceiver: the callback invoked when the request succeeds or fails This value cannot be null.

isEnabledCredentialProviderService

Added in API level 34
public boolean isEnabledCredentialProviderService (ComponentName componentName)

Returns true if the calling application provides a CredentialProviderService that is enabled for the current user, or false otherwise. CredentialProviderServices are enabled on a per-service basis so the individual component name of the service should be passed in here. Usage of this API is encouraged in API level 35 and above. It may throw a NullPointerException on certain devices running other API versions.

Parameters
componentName ComponentName: the component name to check is enabled This value cannot be null.

Returns
boolean

Throws
IllegalArgumentException if the componentName package does not match the calling package name this call will throw an exception
NullPointerException Usage of this API is discouraged as it is not fully functional, and may throw a NullPointerException on certain devices and/or API versions

prepareGetCredential

Added in API level 34
public void prepareGetCredential (GetCredentialRequest request, 
                CancellationSignal cancellationSignal, 
                Executor executor, 
                OutcomeReceiver<PrepareGetCredentialResponseGetCredentialException> callback)

Prepare for a get-credential operation. Returns a PrepareGetCredentialResponse that can launch the credential retrieval UI flow to request a user credential for your app.

This API doesn't invoke any UI. It only performs the preparation work so that you can later launch the remaining get-credential operation (involves UIs) through the getCredential(android.content.Context, android.credentials.PrepareGetCredentialResponse.PendingGetCredentialHandle, android.os.CancellationSignal, java.util.concurrent.Executor, android.os.OutcomeReceiver) API which incurs less latency compared to the getCredential(android.content.Context, android.credentials.GetCredentialRequest, android.os.CancellationSignal, java.util.concurrent.Executor, android.os.OutcomeReceiver) API that executes the whole operation in one call.

Parameters
request GetCredentialRequest: the request specifying type(s) of credentials to get from the user This value cannot be null.

cancellationSignal CancellationSignal: an optional signal that allows for cancelling this call This value may be null.

executor Executor: the callback will take place on this Executor Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread. This value cannot be null.

callback OutcomeReceiver: the callback invoked when the request succeeds or fails This value cannot be null.

registerCredentialDescription

Added in API level 34
public void registerCredentialDescription (RegisterCredentialDescriptionRequest request)

Registers a CredentialDescription for an actively provisioned Credential a CredentialProvider has. This registry will then be used to determine where to fetch the requested Credential from. Not all credential types will be supported. The distinction will be made by the JetPack layer. For the types that are supported, JetPack will add a new key-value pair into GetCredentialRequest. These will not be persistent on the device. The Credential Providers will need to call this API again upon device reboot.

Parameters
request RegisterCredentialDescriptionRequest: the request data This value cannot be null.

Throws
java.lang.UnsupportedOperationException UnsupportedOperationException} if the feature has not been enabled.
com.android.server.credentials.NonCredentialProviderCallerException} if the calling package name is not also listed as a Credential Provider.
java.lang.IllegalArgumentException IllegalArgumentException} if the calling Credential Provider can not handle one or more of the Credential Types that are sent for registration.

unregisterCredentialDescription

Added in API level 34
public void unregisterCredentialDescription (UnregisterCredentialDescriptionRequest request)

Unregisters a CredentialDescription for an actively provisioned Credential that has been registered previously.

Parameters
request UnregisterCredentialDescriptionRequest: the request data This value cannot be null.

Throws
java.lang.UnsupportedOperationException UnsupportedOperationException} if the feature has not been enabled.