Stay organized with collections Save and categorize content based on your preferences.

CredentialManager

public final class CredentialManager

Manages user authentication flows.

An application can call the CredentialManager apis to 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.

This class contains its own exception types. They represent unique failures during the Credential Manager flow. As required, they can be extended for unique types containing new and unique versions of the exception - either with new 'exception types' (same credential class, different exceptions), or inner subclasses and their exception types (a subclass credential class and all their exception types).

For example, if there is an UNKNOWN exception type, assuming the base Exception is ClearCredentialException, we can add an 'exception type' class for it as follows: TODO("Add in new flow with extensive 'getType' function")

class ClearCredentialUnknownException(
    errorMessage: CharSequence? = null
) : ClearCredentialException(TYPE_CLEAR_CREDENTIAL_UNKNOWN_EXCEPTION, errorMessage) {
 // ...Any required impl here...//
 companion object {
      private const val TYPE_CLEAR_CREDENTIAL_UNKNOWN_EXCEPTION: String =
      "androidx.credentials.TYPE_CLEAR_CREDENTIAL_UNKNOWN_EXCEPTION"
  }
}

Furthermore, the base class can be subclassed to a new more specific credential type, which then can further be subclassed into individual exception types. The first is an example of a 'inner credential type exception', and the next is a 'exception type' of this subclass exception.

class UniqueCredentialBasedOnClearCredentialException(
    type: String,
    errorMessage: CharSequence? = null
) : ClearCredentialException(type, errorMessage) {
 // ... Any required impl here...//
}
// .... code and logic .... //
class UniqueCredentialBasedOnClearCredentialUnknownException(
    errorMessage: CharSequence? = null
) : ClearCredentialException(TYPE_UNIQUE_CREDENTIAL_BASED_ON_CLEAR_CREDENTIAL_UNKNOWN_EXCEPTION,
errorMessage) {
// ... Any required impl here ... //
 companion object {
      private const val
      TYPE_UNIQUE_CREDENTIAL_BASED_ON_CLEAR_CREDENTIAL_UNKNOWN_EXCEPTION: String =
      "androidx.credentials.TYPE_CLEAR_CREDENTIAL_UNKNOWN_EXCEPTION"
  }
}

Summary

Nested types
public static class CredentialManager.Companion

Public methods
final void

Clears the current user credential state from all credential providers.
final void

Clears the current user credential state from all credential providers.
static final @NonNull CredentialManager
final @NonNull CreateCredentialResponse
createCredential(
    @NonNull CreateCredentialRequest request,
    @NonNull Activity activity
)

Registers a user credential that can be used to authenticate the user to the app in the future.
final void

Java API for registering a user credential that can be used to authenticate the user to the app in the future.
final @NonNull GetCredentialResponse
getCredential(
    @NonNull GetCredentialRequest request,
    @NonNull Activity activity
)

Requests a credential from the user.
final void
getCredentialAsync(
    @NonNull GetCredentialRequest request,
    @NonNull Activity activity,
    CancellationSignal cancellationSignal,
    @NonNull Executor executor,
    @NonNull CredentialManagerCallback<@NonNull GetCredentialResponse, @NonNull GetCredentialException> callback
)

Java API for requesting a credential from the user.

Public methods

clearCredentialState

public final void clearCredentialState(@NonNull ClearCredentialStateRequest request)

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
@NonNull ClearCredentialStateRequest request

the request for clearing the app user's credential state
Throws
androidx.credentials.exceptions.ClearCredentialException androidx.credentials.exceptions.ClearCredentialException

If the request fails

clearCredentialStateAsync

public final void clearCredentialStateAsync(
    @NonNull ClearCredentialStateRequest request,
    CancellationSignal cancellationSignal,
    @NonNull Executor executor,
    @NonNull CredentialManagerCallback<Void, @NonNull ClearCredentialException> 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
@NonNull ClearCredentialStateRequest request

the request for clearing the app user's credential state
CancellationSignal cancellationSignal

an optional signal that allows for cancelling this call
@NonNull Executor executor

the callback will take place on this executor
@NonNull CredentialManagerCallback<Void, @NonNull ClearCredentialException> callback

the callback invoked when the request succeeds or fails

create

public static final @NonNull CredentialManager create(@NonNull Context context)

createCredential

public final @NonNull CreateCredentialResponse createCredential(
    @NonNull CreateCredentialRequest request,
    @NonNull Activity activity
)

Registers a user credential that can be used to authenticate the user to the app in the future.

The execution potentially launches framework UI flows for a user to view their registration options, grant consent, etc.

Parameters
@NonNull CreateCredentialRequest request

the request for creating the credential
@NonNull Activity activity

the activity used to potentially launch any UI needed
Throws
androidx.credentials.exceptions.CreateCredentialException androidx.credentials.exceptions.CreateCredentialException

If the request fails

createCredentialAsync

public final void createCredentialAsync(
    @NonNull CreateCredentialRequest request,
    @NonNull Activity activity,
    CancellationSignal cancellationSignal,
    @NonNull Executor executor,
    @NonNull CredentialManagerCallback<@NonNull CreateCredentialResponse, @NonNull CreateCredentialException> callback
)

Java API for registering a user credential that can be used to authenticate the user to the app in the future.

The execution potentially launches framework UI flows for a user to view their registration options, grant consent, etc.

Parameters
@NonNull CreateCredentialRequest request

the request for creating the credential
@NonNull Activity activity

an optional activity used to potentially launch any UI needed
CancellationSignal cancellationSignal

an optional signal that allows for cancelling this call
@NonNull Executor executor

the callback will take place on this executor
@NonNull CredentialManagerCallback<@NonNull CreateCredentialResponse, @NonNull CreateCredentialException> callback

the callback invoked when the request succeeds or fails

getCredential

public final @NonNull GetCredentialResponse getCredential(
    @NonNull GetCredentialRequest request,
    @NonNull Activity activity
)

Requests a credential from the user.

The execution potentially launches framework UI flows for a user to view available credentials, consent to using one of them, etc.

Parameters
@NonNull GetCredentialRequest request

the request for getting the credential
@NonNull Activity activity

the activity used to potentially launch any UI needed
Throws
androidx.credentials.exceptions.GetCredentialException androidx.credentials.exceptions.GetCredentialException

If the request fails

getCredentialAsync

public final void getCredentialAsync(
    @NonNull GetCredentialRequest request,
    @NonNull Activity activity,
    CancellationSignal cancellationSignal,
    @NonNull Executor executor,
    @NonNull CredentialManagerCallback<@NonNull GetCredentialResponse, @NonNull GetCredentialException> callback
)

Java API for requesting a credential from the user.

The execution potentially launches framework UI flows for a user to view available credentials, consent to using one of them, etc.

Parameters
@NonNull GetCredentialRequest request

the request for getting the credential
@NonNull Activity activity

an optional activity used to potentially launch any UI needed
CancellationSignal cancellationSignal

an optional signal that allows for cancelling this call
@NonNull Executor executor

the callback will take place on this executor
@NonNull CredentialManagerCallback<@NonNull GetCredentialResponse, @NonNull GetCredentialException> callback

the callback invoked when the request succeeds or fails