CredentialManager
class CredentialManager
kotlin.Any | |
↳ | 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 | |
---|---|
Unit |
clearCredentialState(request: ClearCredentialStateRequest, cancellationSignal: CancellationSignal?, executor: Executor, callback: OutcomeReceiver<Void!, ClearCredentialStateException!>) Clears the current user credential state from all credential providers. |
Unit |
createCredential(context: Context, request: CreateCredentialRequest, cancellationSignal: CancellationSignal?, executor: Executor, callback: OutcomeReceiver<CreateCredentialResponse!, CreateCredentialException!>) Launches the necessary flows to register an app credential for the user. |
Unit |
getCredential(context: Context, request: GetCredentialRequest, cancellationSignal: CancellationSignal?, executor: Executor, callback: OutcomeReceiver<GetCredentialResponse!, GetCredentialException!>) Launches the necessary flows to retrieve an app credential from the user. |
Unit |
getCredential(context: Context, pendingGetCredentialHandle: PrepareGetCredentialResponse.PendingGetCredentialHandle, cancellationSignal: CancellationSignal?, executor: Executor, callback: OutcomeReceiver<GetCredentialResponse!, GetCredentialException!>) Launches the remaining flows to retrieve an app credential from the user, after the completed prefetch work corresponding to the given |
Boolean |
isEnabledCredentialProviderService(componentName: ComponentName) Returns |
Unit |
prepareGetCredential(request: GetCredentialRequest, cancellationSignal: CancellationSignal?, executor: Executor, callback: OutcomeReceiver<PrepareGetCredentialResponse!, GetCredentialException!>) Prepare for a get-credential operation. |
Unit |
Registers a |
Unit |
Unregisters a |
Public methods
clearCredentialState
fun clearCredentialState(
request: ClearCredentialStateRequest,
cancellationSignal: CancellationSignal?,
executor: Executor,
callback: OutcomeReceiver<Void!, ClearCredentialStateException!>
): Unit
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<Void!, ClearCredentialStateException!>: the callback invoked when the request succeeds or fails This value cannot be null . |
createCredential
fun createCredential(
context: Context,
request: CreateCredentialRequest,
cancellationSignal: CancellationSignal?,
executor: Executor,
callback: OutcomeReceiver<CreateCredentialResponse!, CreateCredentialException!>
): Unit
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<CreateCredentialResponse!, CreateCredentialException!>: the callback invoked when the request succeeds or fails This value cannot be null . |
getCredential
fun getCredential(
context: Context,
request: GetCredentialRequest,
cancellationSignal: CancellationSignal?,
executor: Executor,
callback: OutcomeReceiver<GetCredentialResponse!, GetCredentialException!>
): Unit
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<GetCredentialResponse!, GetCredentialException!>: the callback invoked when the request succeeds or fails This value cannot be null . |
getCredential
fun getCredential(
context: Context,
pendingGetCredentialHandle: PrepareGetCredentialResponse.PendingGetCredentialHandle,
cancellationSignal: CancellationSignal?,
executor: Executor,
callback: OutcomeReceiver<GetCredentialResponse!, GetCredentialException!>
): Unit
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<GetCredentialResponse!, GetCredentialException!>: the callback invoked when the request succeeds or fails This value cannot be null . |
isEnabledCredentialProviderService
fun isEnabledCredentialProviderService(componentName: ComponentName): Boolean
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 . |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the componentName package does not match the calling package name this call will throw an exception |
java.lang.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
fun prepareGetCredential(
request: GetCredentialRequest,
cancellationSignal: CancellationSignal?,
executor: Executor,
callback: OutcomeReceiver<PrepareGetCredentialResponse!, GetCredentialException!>
): Unit
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<PrepareGetCredentialResponse!, GetCredentialException!>: the callback invoked when the request succeeds or fails This value cannot be null . |
registerCredentialDescription
fun registerCredentialDescription(request: RegisterCredentialDescriptionRequest): Unit
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 . |
Exceptions | |
---|---|
|
IllegalArgumentException if the calling Credential Provider can not handle one or more of the Credential Types that are sent for registration. |
unregisterCredentialDescription
fun unregisterCredentialDescription(request: UnregisterCredentialDescriptionRequest): Unit
Unregisters a CredentialDescription
for an actively provisioned Credential
that has been registered previously.
Parameters | |
---|---|
request |
UnregisterCredentialDescriptionRequest: the request data This value cannot be null . |
Exceptions | |
---|---|
|
UnsupportedOperationException if the feature has not been enabled. |