CredentialProviderService

@RequiresApi(value = 34)
public abstract class CredentialProviderService extends CredentialProviderService

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.service.credentials.CredentialProviderService
           ↳ androidx.credentials.provider.CredentialProviderService

A CredentialProviderService is a service used to save and retrieve credentials for a given user, upon the request of a client app that typically uses these credentials for sign-in flows.

The credential retrieval and creation/saving is mediated by the Android System that aggregates credentials from multiple credential provider services, and presents them to the user in the form of a selector UI for credential selections/account selections/ confirmations etc.

A CredentialProviderService is only bound to the Android System for the span of a androidx.credentials.CredentialManager get/create API call. The service is bound only if :

  1. The service requires the android.Manifest.permission.BIND_CREDENTIAL_PROVIDER_SERVICE permission.

  2. The user has enabled this service as a credential provider from the settings.

Basic Usage

The basic Credential Manager flow is as such:

  • Client app calls one of the APIs exposed in androidx.credentials.CredentialManager.

  • Android system propagates the developer's request to providers that have been enabled by the user, and can support the androidx.credentials.Credential type specified in the request. We call this the query phase of provider communication. Developer may specify a different set of request parameters to be sent to the provider during this phase.

  • In this query phase, providers, in most cases, will respond with a list of CredentialEntry, and an optional list of Action entries (for the get flow), and a list of CreateEntry (for the create flow). No actual credentials will be returned in this phase.

  • Provider responses are aggregated and presented to the user in the form of a selector UI.

  • User selects an entry on the selector.

  • Android System invokes the PendingIntent associated with this entry, that belongs to the corresponding provider. We call this the final phase of provider communication. The PendingIntent contains the complete request originally created by the developer.

  • Provider finishes the Activity invoked by the PendingIntent by setting the result as the activity is finished.

  • Android System sends back the result to the client app.

The flow described above minimizes the amount of time a service is bound to the system. Calls to the service are considered stateless. If a service wishes to maintain state between the calls, it must do its own state management. Note: The service's process might be killed by the Android System when unbound, for cases such as low memory on the device.

Service Registration

In order for Credential Manager to propagate requests to a given provider service, the provider must:

Summary

Public constructors

Public methods
final void
abstract void

Called by the Android System in response to a client app calling androidx.credentials.CredentialManager.createCredential, to create/save a credential with a credential provider installed on the device.
final void
abstract void

Called by the Android System in response to a client app calling androidx.credentials.CredentialManager.getCredential, to get a credential sourced from a credential provider installed on the device.
final void
abstract void

Called by the Android System in response to a client app calling androidx.credentials.CredentialManager.clearCredentialState.

Inherited methods
From android.content.ComponentCallbacks
void
void
From android.content.ComponentCallbacks2
void
onTrimMemory(int level)
From android.content.Context
boolean
bindIsolatedService(
    @NonNull Intent service,
    @NonNull Context.BindServiceFlags flags,
    @NonNull String instanceName,
    @NonNull Executor executor,
    @NonNull ServiceConnection conn
)
boolean
bindIsolatedService(
    @NonNull Intent service,
    int flags,
    @NonNull String instanceName,
    @NonNull Executor executor,
    @NonNull ServiceConnection conn
)
boolean
bindService(
    @NonNull Intent service,
    @NonNull ServiceConnection conn,
    @NonNull Context.BindServiceFlags flags
)
boolean
bindService(
    @NonNull Intent service,
    @NonNull ServiceConnection conn,
    int flags
)
boolean
bindService(
    @NonNull Intent service,
    @NonNull Context.BindServiceFlags flags,
    @NonNull Executor executor,
    @NonNull ServiceConnection conn
)
boolean
bindService(
    @NonNull Intent service,
    int flags,
    @NonNull Executor executor,
    @NonNull ServiceConnection conn
)
boolean
bindServiceAsUser(
    @NonNull Intent service,
    @NonNull ServiceConnection conn,
    @NonNull Context.BindServiceFlags flags,
    @NonNull UserHandle user
)
boolean
bindServiceAsUser(
    @NonNull Intent service,
    @NonNull ServiceConnection conn,
    int flags,
    @NonNull UserHandle user
)
int
int
@NonNull int[]
checkCallingOrSelfUriPermissions(
    @NonNull List<@NonNull Uri> uris,
    int modeFlags
)
int
int
checkCallingUriPermission(@NonNull Uri uri, int modeFlags)
@NonNull int[]
int
checkContentUriPermissionFull(
    @NonNull Uri uri,
    int pid,
    int uid,
    int modeFlags
)
int
checkPermission(@NonNull String permission, int pid, int uid)
int
int
checkUriPermission(@NonNull Uri uri, int pid, int uid, int modeFlags)
int
checkUriPermission(
    @Nullable Uri uri,
    @Nullable String readPermission,
    @Nullable String writePermission,
    int pid,
    int uid,
    int modeFlags
)
@NonNull int[]
checkUriPermissions(
    @NonNull List<@NonNull Uri> uris,
    int pid,
    int uid,
    int modeFlags
)
void

This method is deprecated. Deprecated in Java
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
createDeviceContext(int deviceId)
@NonNull Context
@NonNull Context
@NonNull Context
createPackageContext(@NonNull String packageName, int flags)
@NonNull Context
createWindowContext(int type, @Nullable Bundle options)
@NonNull Context
createWindowContext(
    @NonNull Display display,
    int type,
    @Nullable Bundle options
)
@NonNull String[]
boolean
boolean
boolean
void
enforceCallingOrSelfPermission(
    @NonNull String permission,
    @Nullable String message
)
void
enforceCallingOrSelfUriPermission(
    @NonNull Uri uri,
    int modeFlags,
    @NonNull String message
)
void
enforceCallingPermission(
    @NonNull String permission,
    @Nullable String message
)
void
enforceCallingUriPermission(
    @NonNull Uri uri,
    int modeFlags,
    @NonNull String message
)
void
enforcePermission(
    @NonNull String permission,
    int pid,
    int uid,
    @Nullable String message
)
void
enforceUriPermission(
    @NonNull Uri uri,
    int pid,
    int uid,
    int modeFlags,
    @NonNull String message
)
void
enforceUriPermission(
    @Nullable Uri uri,
    @Nullable String readPermission,
    @Nullable String writePermission,
    int pid,
    int uid,
    int modeFlags,
    @Nullable String message
)
@NonNull String[]
final int
getColor(int id)
final @NonNull ColorStateList
@NonNull File
@NonNull File
getDir(@NonNull String name, int mode)
final @Nullable Drawable
getDrawable(int id)
@Nullable File
@NonNull File[]
@NonNull File
@NonNull SharedPreferences
getSharedPreferences(@NonNull String name, int mode)
final @NonNull String
getString(int resId)
final @NonNull String
getString(int resId, @NonNull Object... formatArgs)
@NonNull Object
final @NonNull T
<T extends Object> getSystemService(@NonNull Class<@NonNull T> serviceClass)
String
final @NonNull CharSequence
getText(int resId)
void
grantUriPermission(
    @NonNull String toPackage,
    @NonNull Uri uri,
    int modeFlags
)
boolean
moveDatabaseFrom(@NonNull Context sourceContext, @NonNull String name)
boolean
moveSharedPreferencesFrom(
    @NonNull Context sourceContext,
    @NonNull String name
)
final @NonNull TypedArray
final @NonNull TypedArray
obtainStyledAttributes(int resid, @NonNull int[] attrs)
final @NonNull TypedArray
final @NonNull TypedArray
obtainStyledAttributes(
    @Nullable AttributeSet set,
    @NonNull int[] attrs,
    int defStyleAttr,
    int defStyleRes
)
@NonNull FileInputStream
@NonNull FileOutputStream
openFileOutput(@NonNull String name, int mode)
@NonNull SQLiteDatabase
openOrCreateDatabase(
    @NonNull String name,
    int mode,
    @NonNull SQLiteDatabase.CursorFactory factory
)
@NonNull SQLiteDatabase
openOrCreateDatabase(
    @NonNull String name,
    int mode,
    @NonNull SQLiteDatabase.CursorFactory factory,
    @Nullable DatabaseErrorHandler errorHandler
)
@NonNull Drawable

This method is deprecated. Deprecated in Java
void
void
registerDeviceIdChangeListener(
    @NonNull Executor executor,
    @NonNull IntConsumer listener
)
Intent
registerReceiver(
    @Nullable BroadcastReceiver receiver,
    @NonNull IntentFilter filter
)
Intent
registerReceiver(
    @Nullable BroadcastReceiver receiver,
    @NonNull IntentFilter filter,
    int flags
)
Intent
registerReceiver(
    @Nullable BroadcastReceiver receiver,
    @NonNull IntentFilter filter,
    @Nullable String broadcastPermission,
    @Nullable Handler scheduler
)
Intent
registerReceiver(
    @Nullable BroadcastReceiver receiver,
    @NonNull IntentFilter filter,
    @Nullable String broadcastPermission,
    @Nullable Handler scheduler,
    int flags
)
void

This method is deprecated. Deprecated in Java
void

This method is deprecated. Deprecated in Java
void
void
void
revokeUriPermission(@NonNull Uri uri, int modeFlags)
void
revokeUriPermission(
    @NonNull String targetPackage,
    @NonNull Uri uri,
    int modeFlags
)
void
void
sendBroadcast(@NonNull Intent intent, @Nullable String receiverPermission)
void
sendBroadcast(
    @NonNull Intent intent,
    @Nullable String receiverPermission,
    @Nullable Bundle options
)
void
void
sendBroadcastAsUser(
    @NonNull Intent intent,
    @NonNull UserHandle user,
    String receiverPermission
)
void
sendBroadcastWithMultiplePermissions(
    @NonNull Intent intent,
    @NonNull String[] receiverPermissions
)
void
sendOrderedBroadcast(
    @NonNull Intent intent,
    @Nullable String receiverPermission
)
void
sendOrderedBroadcast(
    @NonNull Intent intent,
    @Nullable String receiverPermission,
    @Nullable Bundle options
)
void
sendOrderedBroadcast(
    @NonNull Intent intent,
    @Nullable String receiverPermission,
    @Nullable BroadcastReceiver resultReceiver,
    @Nullable Handler scheduler,
    int initialCode,
    @Nullable String initialData,
    @Nullable Bundle initialExtras
)
void
sendOrderedBroadcast(
    @NonNull Intent intent,
    @Nullable String receiverPermission,
    @Nullable Bundle options,
    @Nullable BroadcastReceiver resultReceiver,
    @Nullable Handler scheduler,
    int initialCode,
    @Nullable String initialData,
    @Nullable Bundle initialExtras
)
void
sendOrderedBroadcast(
    @NonNull Intent intent,
    @Nullable String receiverPermission,
    @Nullable String receiverAppOp,
    @Nullable BroadcastReceiver resultReceiver,
    @Nullable Handler scheduler,
    int initialCode,
    @Nullable String initialData,
    @Nullable Bundle initialExtras
)
void
sendOrderedBroadcastAsUser(
    @NonNull Intent intent,
    @NonNull UserHandle user,
    @Nullable String receiverPermission,
    @Nullable BroadcastReceiver resultReceiver,
    @Nullable Handler scheduler,
    int initialCode,
    @Nullable String initialData,
    @Nullable Bundle initialExtras
)
void

This method is deprecated. Deprecated in Java
void

This method is deprecated. Deprecated in Java
void

This method is deprecated. Deprecated in Java
void
sendStickyOrderedBroadcast(
    @NonNull Intent intent,
    @Nullable BroadcastReceiver resultReceiver,
    @Nullable Handler scheduler,
    int initialCode,
    @Nullable String initialData,
    @Nullable Bundle initialExtras
)

This method is deprecated. Deprecated in Java
void
sendStickyOrderedBroadcastAsUser(
    @NonNull Intent intent,
    @NonNull UserHandle user,
    @Nullable BroadcastReceiver resultReceiver,
    @Nullable Handler scheduler,
    int initialCode,
    @Nullable String initialData,
    @Nullable Bundle initialExtras
)

This method is deprecated. Deprecated in Java
void
setTheme(int resid)
void

This method is deprecated. Deprecated in Java
void

This method is deprecated. Deprecated in Java
void
startActivities(@NonNull Intent[] intents)
void
startActivities(@NonNull Intent[] intents, @Nullable Bundle options)
void
void
@Nullable ComponentName
boolean
startInstrumentation(
    @NonNull ComponentName className,
    @Nullable String profileFile,
    @Nullable Bundle arguments
)
void
startIntentSender(
    @NonNull IntentSender intent,
    @Nullable Intent fillInIntent,
    int flagsMask,
    int flagsValues,
    int extraFlags
)
void
startIntentSender(
    @NonNull IntentSender intent,
    @Nullable Intent fillInIntent,
    int flagsMask,
    int flagsValues,
    int extraFlags,
    @Nullable Bundle options
)
@Nullable ComponentName
boolean
void
void
void
void
void
updateServiceGroup(
    @NonNull ServiceConnection conn,
    int group,
    int importance
)
From android.content.ContextWrapper
void
@NonNull Context
@NonNull ApplicationInfo
@NonNull AssetManager
@NonNull AttributionSource
@Nullable String
@NonNull Context
@NonNull File
@NonNull ClassLoader
@NonNull File
@NonNull ContentResolver
@NonNull File
int
@Nullable Display
@Nullable File
@NonNull File[]
@NonNull File[]
@NonNull File
@NonNull Executor
@NonNull Looper
@NonNull File
@NonNull File
@NonNull File[]
@NonNull String
@NonNull String
@NonNull PackageManager
@NonNull String
@NonNull String
@Nullable ContextParams
@NonNull Resources
@NonNull Resources.Theme
@NonNull Drawable

This method is deprecated. Deprecated in Java
int

This method is deprecated. Deprecated in Java
int

This method is deprecated. Deprecated in Java
boolean
boolean
boolean
void
sendOrderedBroadcast(
    @NonNull Intent intent,
    int initialCode,
    @Nullable String receiverPermission,
    @Nullable String receiverAppOp,
    @Nullable BroadcastReceiver resultReceiver,
    @Nullable Handler scheduler,
    @Nullable String initialData,
    @Nullable Bundle initialExtras,
    @Nullable Bundle options
)
From android.app.Service
void
dump(
    @NonNull FileDescriptor fd,
    @NonNull PrintWriter writer,
    @NonNull String[] args
)
final @NonNull Application
final int
final @NonNull IBinder
void
void
void
void
onStart(@NonNull Intent intent, int startId)

This method is deprecated. Deprecated in Java
int
onStartCommand(@NonNull Intent intent, int flags, int startId)
void
void
onTimeout(int startId)
void
onTimeout(int startId, int fgsType)
boolean
final void
startForeground(int id, @NonNull Notification notification)
final void
startForeground(
    int id,
    @NonNull Notification notification,
    int foregroundServiceType
)
final void
stopForeground(int notificationBehavior)
final void
stopForeground(boolean removeNotification)

This method is deprecated. Deprecated in Java
final void
final void
stopSelf(int startId)
final boolean
stopSelfResult(int startId)

Public constructors

CredentialProviderService

Added in 1.2.0
public CredentialProviderService()

Public methods

onBeginCreateCredential

Added in 1.2.0
public final void onBeginCreateCredential(
    @NonNull BeginCreateCredentialRequest request,
    @NonNull CancellationSignal cancellationSignal,
    @NonNull OutcomeReceiver<@NonNull BeginCreateCredentialResponse, @NonNull CreateCredentialException> callback
)

onBeginCreateCredentialRequest

Added in 1.2.0
public abstract void onBeginCreateCredentialRequest(
    @NonNull BeginCreateCredentialRequest request,
    @NonNull CancellationSignal cancellationSignal,
    @NonNull OutcomeReceiver<@NonNull BeginCreateCredentialResponse, @NonNull CreateCredentialException> callback
)

Called by the Android System in response to a client app calling androidx.credentials.CredentialManager.createCredential, to create/save a credential with a credential provider installed on the device.

Credential provider services must extend this method in order to handle a BeginCreateCredentialRequest request. Once processed, the service must call one of the callback methods to notify the result of the request.

This API call is referred to as the query phase of the original create request from the client app. In this phase, provider must process the request parameters in the BeginCreateCredentialRequest and return a list of CreateEntry whereby every entry represents an account/group where the user will be storing the credential. Each CreateEntry must contain a PendingIntent that will lead the user to an activity in the credential provider's app that will complete the actual credential creation.

When user selects one of the CreateEntry, the associated PendingIntent will be invoked and the provider will receive the complete request as part of the extras in the resulting activity. Provider must retrieve the request through PendingIntentHandler.retrieveProviderCreateCredentialRequest. Once the activity is complete, and the credential is created, provider must set back the response through PendingIntentHandler.setCreateCredentialResponse.

Parameters
@NonNull BeginCreateCredentialRequest request

the BeginCreateCredentialRequest to handle See BeginCreateCredentialResponse for the response to be returned
@NonNull CancellationSignal cancellationSignal

signal for observing cancellation requests. The system will use this to notify you that the result is no longer needed and you should stop handling it in order to save your resources
@NonNull OutcomeReceiver<@NonNull BeginCreateCredentialResponse, @NonNull CreateCredentialException> callback

the callback object to be used to notify the response or error

onBeginGetCredential

Added in 1.2.0
public final void onBeginGetCredential(
    @NonNull BeginGetCredentialRequest request,
    @NonNull CancellationSignal cancellationSignal,
    @NonNull OutcomeReceiver<@NonNull BeginGetCredentialResponse, @NonNull GetCredentialException> callback
)

onBeginGetCredentialRequest

Added in 1.2.0
public abstract void onBeginGetCredentialRequest(
    @NonNull BeginGetCredentialRequest request,
    @NonNull CancellationSignal cancellationSignal,
    @NonNull OutcomeReceiver<@NonNull BeginGetCredentialResponse, @NonNull GetCredentialException> callback
)

Called by the Android System in response to a client app calling androidx.credentials.CredentialManager.getCredential, to get a credential sourced from a credential provider installed on the device.

Credential provider services must extend this method in order to handle a BeginGetCredentialRequest request. Once processed, the service must call one of the callback methods to notify the result of the request.

This API call is referred to as the query phase of the original get request from the client app. In this phase, provider must go over all the android.service.credentials.BeginGetCredentialOption, and add corresponding a CredentialEntry to the BeginGetCredentialResponse. Each CredentialEntry should contain meta-data to be shown on the selector UI. In addition, each CredentialEntry must contain a PendingIntent. Optionally, providers can also add Action entries for any non-credential related actions that they want to offer to the users e.g. opening app, managing credentials etc.

When user selects one of the CredentialEntry, final phase of the original client's get-request flow starts. The Android System attached the complete androidx.credentials.provider.ProviderGetCredentialRequest to an intent extra of the activity that is started by the pending intent. The request must be retrieved through PendingIntentHandler.retrieveProviderGetCredentialRequest. This final request will only contain a single androidx.credentials.CredentialOption that contains the parameters of the credential the user has requested. The provider service must retrieve this credential and return through PendingIntentHandler.setGetCredentialResponse.

Handling locked provider apps If the provider app is locked, and the provider cannot provide any meta-data based CredentialEntry, provider must set an AuthenticationAction on the BeginGetCredentialResponse. The PendingIntent set on this entry must lead the user to an >unlock activity. Once unlocked, the provider must retrieve all credentials, and set the list of CredentialEntry and the list of optional Action as a result of the >unlock activity through PendingIntentHandler.setBeginGetCredentialResponse.

Parameters
@NonNull BeginGetCredentialRequest request

the ProviderGetCredentialRequest to handle See BeginGetCredentialResponse for the response to be returned
@NonNull CancellationSignal cancellationSignal

signal for observing cancellation requests. The system will use this to notify you that the result is no longer needed and you should stop handling it in order to save your resources
@NonNull OutcomeReceiver<@NonNull BeginGetCredentialResponse, @NonNull GetCredentialException> callback

the callback object to be used to notify the response or error
See also
CredentialEntry

for how an entry representing a credential must be built
Action

for how a non-credential related action should be built
AuthenticationAction

for how an entry that navigates the user to an unlock flow can be built

onClearCredentialState

Added in 1.2.0
public final void onClearCredentialState(
    @NonNull ClearCredentialStateRequest request,
    @NonNull CancellationSignal cancellationSignal,
    @NonNull OutcomeReceiver<@NonNull Void, @NonNull ClearCredentialStateException> callback
)

onClearCredentialStateRequest

Added in 1.2.0
public abstract void onClearCredentialStateRequest(
    @NonNull ProviderClearCredentialStateRequest request,
    @NonNull CancellationSignal cancellationSignal,
    @NonNull OutcomeReceiver<Void, @NonNull ClearCredentialException> callback
)

Called by the Android System in response to a client app calling androidx.credentials.CredentialManager.clearCredentialState. A client app typically calls this API on instances like sign-out when the intention is that the providers clear any state that they may have maintained for the given user.

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.

An example scenario of a state that is maintained and is expected to be cleared on this call, is when an active credential session is being stored to limit sign-in options in the result of subsequent get-request calls. When a user explicitly signs out of the app, the next time, the client app may want their users to see all options and hence will call this API first to make sure credential providers can clear the state maintained previously.

Parameters
@NonNull ProviderClearCredentialStateRequest request

the request for the credential provider to handle
@NonNull CancellationSignal cancellationSignal

signal for observing cancellation requests. The system will use this to notify you that the result is no longer needed and you should stop handling it in order to save your resources
@NonNull OutcomeReceiver<Void, @NonNull ClearCredentialException> callback

the callback object to be used to notify the response or error