1 /* 2 * Copyright 2022 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package androidx.credentials 18 19 import android.content.Context 20 import android.os.CancellationSignal 21 import androidx.annotation.RequiresApi 22 import androidx.credentials.exceptions.ClearCredentialException 23 import androidx.credentials.exceptions.CreateCredentialException 24 import androidx.credentials.exceptions.GetCredentialException 25 import java.util.concurrent.Executor 26 27 /** 28 * Provider interface to be implemented by system credential providers that will fulfill Credential 29 * Manager requests. The implementation **must** have a constructor that takes in a context. 30 * 31 * <p>Note that for SDK version 33 and below, this interface can be implemented by any OEM provider 32 * that wishes to return credentials. The implementation must have a constructor with a context 33 * parameter. A provider must : 34 * <ol> 35 * <li>Release a dedicated provider library that developers can add as a dependency. 36 * <li>Include an empty CredentialProviderService in the provider library for the purposes of 37 * exposing a meta-data tag in the Android Manifest file. 38 * <li>Add the name of the class that is implementing this interface, as a value to the meta-data 39 * tag described above. 40 * <li>Make sure that there is only one provider implementation on the device. If the device already 41 * has a provider installed, and the developer specifies more than one provider dependencies, 42 * credential manager will error out. 43 * </ol> 44 * 45 * <p>For SDK version 34 and above, this interface will only be implemented by an internal class 46 * that will route all requests to the android framework. Providers will need to register directly 47 * with the framework to provide credentials. 48 */ 49 interface CredentialProvider { 50 /** 51 * Invoked on a request to get a credential. 52 * 53 * @param context the client calling context used to potentially launch any UI needed 54 * @param request the request for getting the credential 55 * @param cancellationSignal an optional signal that allows for cancelling this call 56 * @param executor the callback will take place on this executor 57 * @param callback the callback invoked when the request succeeds or fails 58 */ onGetCredentialnull59 fun onGetCredential( 60 context: Context, 61 request: GetCredentialRequest, 62 cancellationSignal: CancellationSignal?, 63 executor: Executor, 64 callback: CredentialManagerCallback<GetCredentialResponse, GetCredentialException>, 65 ) 66 67 /** 68 * Invoked on a request to create a credential. 69 * 70 * @param context the client calling context used to potentially launch any UI needed 71 * @param request the request for creating the credential 72 * @param cancellationSignal an optional signal that allows for cancelling this call 73 * @param executor the callback will take place on this executor 74 * @param callback the callback invoked when the request succeeds or fails 75 */ 76 fun onCreateCredential( 77 context: Context, 78 request: CreateCredentialRequest, 79 cancellationSignal: CancellationSignal?, 80 executor: Executor, 81 callback: CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException>, 82 ) 83 84 /** Determines whether the provider is available on this device, or not. */ 85 fun isAvailableOnDevice(): Boolean 86 87 /** 88 * Invoked on a request to clear a credential. 89 * 90 * @param request the request for clearing the app user's credential state 91 * @param cancellationSignal an optional signal that allows for cancelling this call 92 * @param executor the callback will take place on this executor 93 * @param callback the callback invoked when the request succeeds or fails 94 */ 95 fun onClearCredential( 96 request: ClearCredentialStateRequest, 97 cancellationSignal: CancellationSignal?, 98 executor: Executor, 99 callback: CredentialManagerCallback<Void?, ClearCredentialException>, 100 ) 101 102 /** 103 * Invoked on a request to prepare for a get-credential operation 104 * 105 * @param request the request for getting the credential 106 * @param cancellationSignal an optional signal that allows for cancelling this call 107 * @param executor the callback will take place on this executor 108 * @param callback the callback invoked when the request succeeds or fails 109 */ 110 @RequiresApi(34) 111 fun onPrepareCredential( 112 request: GetCredentialRequest, 113 cancellationSignal: CancellationSignal?, 114 executor: Executor, 115 callback: CredentialManagerCallback<PrepareGetCredentialResponse, GetCredentialException>, 116 ) {} 117 118 /** 119 * Complete on a request to get a credential represented by the [pendingGetCredentialHandle]. 120 * 121 * @param context the client calling context used to potentially launch any UI needed 122 * @param pendingGetCredentialHandle the handle representing the pending operation to resume 123 * @param cancellationSignal an optional signal that allows for cancelling this call 124 * @param executor the callback will take place on this executor 125 * @param callback the callback invoked when the request succeeds or fails 126 */ 127 @RequiresApi(34) onGetCredentialnull128 fun onGetCredential( 129 context: Context, 130 pendingGetCredentialHandle: PrepareGetCredentialResponse.PendingGetCredentialHandle, 131 cancellationSignal: CancellationSignal?, 132 executor: Executor, 133 callback: CredentialManagerCallback<GetCredentialResponse, GetCredentialException>, 134 ) {} 135 } 136