Authentication API

You can manage the authentication process in your application code using the authentication API provided by ArcGIS Maps SDK for Kotlin. This is the same API used by the Authenticator toolkit component, and gives you fine-grained control over the authentication process. When using the API rather than the toolkit, you are responsible for the code that handles authentication details.

The central class in the authentication API is the AuthenticationManager. This is a static property of the ArcGISEnvironment.

1
ArcGISEnvironment.authenticationManager

The AuthenticationManager provides:

• Credential stores for your application to hold ArcGIS and network credentials that are automatically checked when your application attempts to connect to secure resources. These stores can be made persistent so that user does not have to sign in again when the application is re-launched. For more information, see Create and store credentials.
• ArcGIS and network challenge handlers that allow your application to respond to the authentication challenges. For example, you can write code to present the user with a login screen and then continue to authenticate with those credentials. For more information, see Handle authentication challenges.

Handle authentication challenges

If your application attempts to access a secure resource and there is no matching credential in the credential store, an authentication challenge is raised:

• ArcGISAuthenticationChallenge is raised if the ArcGIS secured resource requires OAuth, Identity-Aware Proxy (IAP), or ArcGIS Token authentication.
• NetworkAuthenticationChallenge is raised if the ArcGIS secured resource requires network credentials, such as Integrated Windows Authentication (IWA) or Public Key Infrastructure (PKI).

You can catch and respond to these authentication challenges using the ArcGISAuthenticationChallengeHandler and NetworkAuthenticationChallengeHandler, respectively. These are functional interfaces that each implement a single abstract method called handleArcGISAuthenticationChallenge() and handleNetworkAuthenticationChallenge() respectively. Instead of creating a class that implements the interface, you can use a lambda expression.

ArcGIS authentication challenge handler

The ArcGISAuthenticationChallengeHandler is used to handle authentication challenges from ArcGIS secured resources that require OAuth, Identity-Aware Proxy (IAP), or ArcGIS Token authentication. The recommended way to handle authentication changes is to use the Authenticator component in the ArcGIS Maps SDK for Kotlin toolkit. If you choose not to use Authenticator, you can handle the challenge in your code and return one of the following subclasses of the ArcGISAuthenticationChallengeResponse sealed class:

• ContinueWithCredential(ArcGISCredential) - Handles the challenge with the specified credential.
• ContinueAndFail - Handles the challenge without a credential, causing it to fail with the original authentication error
• ContinueAndFailWithError - Handles the challenge with an error that occurred while trying to generate a credential. The request that issued the authentication challenge will fail with the given error.
• Cancel - Cancels the request that initiated the challenge.

1. Create a custom ArcGISAuthenticationChallengeHandler and assign it to the AuthenticationManager.arcGISAuthenticationChallengeHandler.

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
               ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler =
                   ArcGISAuthenticationChallengeHandler { challenge ->
                       when (challenge.type) {
                           ArcGISAuthenticationChallengeType.Iap -> {
                               val matchingIapConfiguration = iapConfigurations.first {
                                   it.canBeUsedForUrl(challenge.requestUrl)
                               }
                               val iapCredential =
                                   IapCredential.create(matchingIapConfiguration) { iapSignIn ->
                                       // Prompt to open browser for IAP sign in
                                       // ...
                                   }.getOrThrow()
                               ArcGISAuthenticationChallengeResponse.ContinueWithCredential(
                                   iapCredential
                               )
                           }
   
                           ArcGISAuthenticationChallengeType.OAuthOrToken -> {
                               val matchingOAuthUserConfiguration = oAuthUserConfigurations.first {
                                   it.canBeUsedForUrl(challenge.requestUrl)
                               }
                               val oAuthUserCredential =
                                   OAuthUserCredential.create(matchingOAuthUserConfiguration) { oAuthUserSignIn ->
                                       // Prompt to open browser and sign in with Oauth username and password.
                                       // ...
                               }.getOrThrow()
                               ArcGISAuthenticationChallengeResponse.ContinueWithCredential(
                                   oAuthUserCredential
                               )
                           }
   
                           ArcGISAuthenticationChallengeType.Token -> {
                               val tokenCredential =
                                   TokenCredential.createWithChallenge(challenge, username, password)
                                       .getOrThrow()
                               ArcGISAuthenticationChallengeResponse.ContinueWithCredential(
                                   tokenCredential
                               )
                           }
                       }
                   }
   

Network authentication challenge handler

The NetworkAuthenticationChallengeHandler is used to handle authentication challenges from ArcGIS secured resources that require network credentials, such as Integrated Windows Authentication (IWA) or Public Key Infrastructure (PKI). It returns one of the following subclasses of the NetworkAuthenticationChallengeResponse sealed class.

• ContinueWithCredential(NetworkCredential) - Handles the challenge with the specified credential.
• ContinueAndFail - Handles the challenge without a credential, causing it to fail with the original authentication error
• ContinueAndFailWithError - Handles the challenge with an error that occurred while trying to generate a credential. The request that issued the authentication challenge will fail with the given error.
• Cancel - Cancels the request that initiated the challenge.

Create a custom NetworkAuthenticationChallengeHandler and pass it to the AuthenticationManager.networkAuthenticationChallengeHandler.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
ArcGISEnvironment.authenticationManager.networkAuthenticationChallengeHandler =
    NetworkAuthenticationChallengeHandler { authenticationChallenge ->
        when (authenticationChallenge.networkAuthenticationType) {
            is NetworkAuthenticationType.UsernamePassword ->
                // Create the Password Credential
                val credential = PasswordCredential(username, password)
                NetworkAuthenticationChallengeResponse.ContinueWithCredential(credential)
            is NetworkAuthenticationType.ServerTrust ->
                NetworkAuthenticationChallengeResponse.ContinueWithCredential(ServerTrust)
            is NetworkAuthenticationType.Certificate -> {
                val selectedAlias = showCertificatePicker(activityContext)
                selectedAlias?.let {
                    NetworkAuthenticationChallengeResponse.ContinueWithCredential(CertificateCredential(it))
                } ?: NetworkAuthenticationChallengeResponse.ContinueAndFail
            }
        }
    }

Create and store credentials

When an authentication challenge is raised, your application can create a credential that is held in the ArcGIS and network credential stores provided by the AuthenticationManager.

• ArcGISCredentialStore stores ArcGIS credentials.
• NetworkCredentialStore stores Network credentials.

These credential stores exist for the lifetime of the application. They ensure that an authentication challenge is only raised if a matching credential does not exist in the store. If you want to avoid prompting users for credentials between application sessions, persist the credential stores using the companion functions ArcGISCredentialStore.createWithPersistence() and NetworkCredentialStore.createWithPersistence(). This uses Android's EncryptedSharedPreferences.

1
2
3
4
5
6
7
lifecycleScope.launch {
  val arcGISCredentialStore = ArcGISCredentialStore.createWithPersistence().getOrThrow()
  ArcGISEnvironment.authenticationManager.arcGISCredentialStore = arcGISCredentialStore

  val networkCredentialStore = NetworkCredentialStore.createWithPersistence().getOrThrow()
  ArcGISEnvironment.authenticationManager.networkCredentialStore = networkCredentialStore
}

During application sign-out, you should revoke all tokens and clear all credentials from the credential stores.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
    val arcGISCredentialStore = ArcGISEnvironment.authenticationManager.arcGISCredentialStore
    val networkCredentialStore =
        ArcGISEnvironment.authenticationManager.networkCredentialStore
        arcGISCredentialStore.getCredentials ().forEach {
            when {
                it is OAuthUserCredential -> {
                    it.revokeToken()
                }

                it is IapCredential -> {
                    it.invalidate { iapSignOut ->
                        promptForIapSignOut(iapSignOut)
                    }
                }
        }
        networkCredentialStore.removeAll()
        arcGISCredentialStore.removeAll()