Types of credentials

You can access resources secured with user authentication, app authentication, or network authentication using the available credential types.

• ArcGIS credentials are used to access resources secured by ArcGIS authentication methods, such as OAuth, Identity-Aware Proxy (IAP), and ArcGIS token. For more information, see ArcGIS credentials.
• Network credentials are used to access resources secured by network authentication methods, such as Integrated Windows Authentication (IWA) and Client Certificate (PKI). For more information, see Network credentials.

ArcGIS credentials

You can access secure resources with user authentication or app authentication using any of the following credential types:

• OAuthUserCredential - A credential object used to access OAuth token-secured ArcGIS resources with a specific OAuthUserConfiguration.
• IapCredential - A credential object used to access ArcGIS Enterprise resources that are secured behind an Identity-Aware Proxy (IAP). You can create the credential using an IapConfiguration.
• OAuthApplicationCredential - A credential object used to access OAuth token-secured ArcGIS resources using the application's credentials.
• TokenCredential - A credential object used to access token-secured ArcGIS resources.
• PregeneratedTokenCredential - A credential object used to access token-secured ArcGIS resources using a token that is generated outside of your application.

If you know the services domain/server context, you can create an ArcGIS credential independent of loading the specific resource and store it in the ArcGISCredentialStore.

OAuthUserCredential

To create an OAuthUserCredential, instantiate an OAuthUserConfiguration with a valid portal URL, client ID, and redirect URL, and wrap the instance in a list. You must present a prompt, in a browser supported by the device, for the user to enter their username and password. The response from the browser should be handled within your activity or the fragment that launched the browser prompt. Once the OAuthUserCredential is created, you can to access the token information by calling getTokenInfo() on the credential.

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
        // Define OAuthConfiguration
        val oAuthUserConfiguration = OAuthUserConfiguration(
            "<portal URL>",
            "<ClientID>",
            "<redirectURI>"
        )

        lifecycleScope.launch {
            val oAuthUserCredential = OAuthUserCredential.create(oAuthUserConfiguration) { oAuthUserSignIn ->
                promptForOAuthUserSignIn(oAuthUserSignIn)
            }.getOrThrow()

            oAuthUserCredential.getTokenInfo()
        }

See the Android documentation for details about how to launch custom Chrome tabs in Android and work with getting result from an activity. If you use the Authenticator in the Toolkit, this is handled for you.

To see this authentication in action, look at the Authenticate with OAuth sample.

IapCredential

The IapCredential supports access to an ArcGIS Enterprise portal and its services that are protected behind an Identity-Aware Proxy (IAP). You must present a prompt, in a browser supported by the device, for the user to enter their username and password. The response from the browser should be handled within your activity or the fragment that launched the browser prompt.

To initiate an IAP authorization workflow, create an IapConfiguration to store your application's registration details and use it to create an IapCredential. Follow the steps below to create an IapCredential:

1. To establish trust between your application and the IAP, you administrator registers your application with the Microsoft Identity Platform. Following this, you can review the client ID, tenant ID, redirect url, and so on.

2. Create the IapConfiguration using these app registration details. Depending on your workflow, you can initialize an IapConfiguration by either providing the details in a JSON file or supplying them directly in the application's code.

   1. To initialize the IapConfiguration with a JSON file, create a JSON file containing the following key/value pairs:

      Use dark colors for code blocksCopy

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      {
       "authorize_url" : "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize",
       "token_url" : "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token",
       "logout_url" : "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/logout",
       "client_id" : "<client_id>",
       "redirect_url" : "<redirect_url>",
       "scope" : [
           "<client_id>/.default",
           "offline_access",
           "openid",
           "profile"
       ],
       "hosts_behind_proxy" : ["*.domain.com"],
       "authorization_prompt_type" : "<empty string, none, login, consent, or select_account>"
      }

      The keys are defined as follows:

      • authorize_url - The authorization endpoint of the Identity-Aware Proxy (IAP) portal.
      • token_url - The token endpoint of the Identity-Aware Proxy (IAP) portal.
      • logout_url - The logout endpoint of the Identity-Aware Proxy (IAP) portal.
      • client_id - A unique identifier associated with an application that is registered with the Identity-Aware Proxy (IAP) portal.
      • redirect_url - The URL that the Identity-Aware Proxy (IAP) login and logout pages will redirect to when authentication completes. The scheme of this URL must be registered as a custom URL scheme in the application.
      • scope - The scope of user's account.
      • hosts_behind_proxy - The hosts to be accessed behind the Identity-Aware Proxy (IAP).
      • authorization_prompt_type - The type of user interaction required for authentication and consent while signing in to the Identity-Aware Proxy (IAP).

   2. Create the IapConfiguration using the IapConfiguration.create(path) companion function.

      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
      109
      110
      111
      112
      113
      114
      115
      116
      117
      118
      119
      120
      121
      122
      123
      124
      125
      126
      127
      128
      129
      130
      131
      132
      133
      134
      135
      136
      137
      138
      139
      140
      141
      142
      143
      144
      145
      146
      147
      148
      149
      150
      151
      152
      153
      154
      155
      156
      157
      158
      159
      160
      161
      162
                  val iapConfigurationFromJson = IapConfiguration.create("/path/to/IAP/configuration/file.json").getOrElse { error ->
                      showMessage(error.message.toString())
                  }
      

      If the JSON file is missing any required properties, the IapConfiguration will fail.

   3. Alternatively, create the IapConfiguration by specifying each parameter in the IapConfiguration.create() companion function.

      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
      109
      110
      111
      112
      113
      114
      115
      116
      117
      118
      119
      120
      121
      122
      123
      124
      125
      126
      127
      128
      129
      130
      131
      132
      133
      134
      135
      136
      137
      138
      139
      140
      141
      142
      143
      144
      145
      146
      147
      148
      149
      150
      151
      152
      153
      154
      155
      156
      157
      158
      159
      160
      161
      162
                  val iapConfiguration = IapConfiguration.create(
                      authorizeUrl = "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize",
                      tokenUrl = "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token",
                      logoutUrl = "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/logout",
                      clientId = "<client_id>",
                      clientSecret = "<client_secret>",
                      redirectUrl = "<redirect_url>",
                      iapClientId = "<iap_client_id>",
                      scopes = listOf(
                          "<client_id>/.default", "offline_access", "openid", "profile"
                      ),
                      hostsBehindProxy = listOf("*.domain.com"),
                      authorizationPromptType = IapAuthorizationPromptType.Unspecified
                  )
      

   Best Practice: To avoid storing secure information in your app's code, the recommended approach is to use the IapConfiguration.create(path) companion function using a JSON file on disk to create an IapConfiguration.

3. Implement the functional interface ArcGISAuthenticationChallengeHandler. Inside the lambda, verify the challenge is of type ArcGISAuthenticationChallengeType.Iap.

   Use dark colors for code blocks

   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
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
   156
   157
   158
   159
   160
   161
   162
               ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler =
                   ArcGISAuthenticationChallengeHandler { challenge ->
   
                       if (challenge.type == ArcGISAuthenticationChallengeType.Iap) {
   
                           val matchingIapConfiguration = iapConfigurations.first { iapConfiguration ->
   
                           }
   
                       }
   
                   }
   

4. Call IapConfiguration.canBeUsedForUrl() to check if the configuration can be used for the requestUrl contained in the challenge. A configuration can be used for a URL if the URL's host matches one of the hosts specified in the configuration's hosts behind proxy.

   Use dark colors for code blocks

   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
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
   156
   157
   158
   159
   160
   161
   162
               ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler =
                   ArcGISAuthenticationChallengeHandler { challenge ->
   
                       if (challenge.type == ArcGISAuthenticationChallengeType.Iap) {
   
                           val matchingIapConfiguration = iapConfigurations.first { iapConfiguration ->
   
                               iapConfiguration.canBeUsedForUrl(challenge.requestUrl)
   
                           }
   
                       }
   
                   }
   

5. Create an IapCredential by calling the IapCredential.create() companion function and passing in the IapConfiguration. This presents the sign-in page for the user to enter their username and password. Once the IapCredential is created, it is added to the ArcGISCredentialStore, and you can access token information by calling getTokenInfo() on the credential.

   Use dark colors for code blocks

   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
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
   156
   157
   158
   159
   160
   161
   162
               ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler =
                   ArcGISAuthenticationChallengeHandler { challenge ->
   
                       if (challenge.type == ArcGISAuthenticationChallengeType.Iap) {
   
                           val matchingIapConfiguration = iapConfigurations.first { iapConfiguration ->
   
                               iapConfiguration.canBeUsedForUrl(challenge.requestUrl)
   
                           }
   
                           iapCredential =
                               IapCredential.create(matchingIapConfiguration) { iapSignIn ->
                                   promptForIapSignIn(iapSignIn)
                                   // ...
                               }.getOrThrow()
                           val iapTokenInfo = iapCredential.getTokenInfo().getOrThrow()
   
                           ArcGISAuthenticationChallengeResponse.ContinueWithCredential(
                               iapCredential
                           )
   
                       }
   
                       // Handle other types of ArcGIS AuthenticationChallenge.
                       else if (challenge.type == ArcGISAuthenticationChallengeType.OAuthOrToken) {
                           // ...
   
                   }
   

6. During application sign-out, you must invalidate the credential by calling IapCredential.invalidate(). This will present a Microsoft page that allows the user to sign-out. Note that after a successful sign-out, the user must click the Cancel button to return to your application.

   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
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
   156
   157
   158
   159
   160
   161
   162
               val signOutRequestResult = iapCredential.invalidate { iapSignOut ->
                   promptForIapSignOut(iapSignOut)
               }
               if (signOutRequestResult.isSuccess) {
                   showMessage("Invalidation of the IAP session was successful")
               } else {
                   showMessage("Invalidation of the IAP session failed: ${signOutRequestResult.exceptionOrNull()?.message}")
               }
   

TokenCredential

To create a TokenCredential, provide a secured service URL, valid username, and password. Optionally, you can specify token expiration minutes. Once a TokenCredential is created, you can access token information by calling getTokenInfo() on the credential.

1
2
3
4
5
6
7
scope.launch {
    TokenCredential.create(requestUrl,username, password, 30).onSuccess {
        // Get accesstoken from credential
        var tokenInfo = it.getTokenInfo().getOrNull()
        var accessToken = tokenInfo?.accessToken
    }
}

PregeneratedTokenCredential

To create a PregeneratedTokenCredential, provide a previously generated short or long-lived access token. Use this when the access token is created using the generateToken REST endpoint directly. You must provide the referer if one was used while generating the token.

1
2
3
var accessToken = "xxxxxxx"
var tokenInfo = val tokenInfo = TokenInfo(accessToken, Instant.now().plus(2, ChronoUnit.HOURS), true)
var pregeneratedTokenCredential = PregeneratedTokenCredential(requestUrl, tokenInfo)

OAuthApplicationCredential

To create an OAuthApplicationCredential, provide a valid portal URL, a client ID, and a client secret. Optionally, you can specify the token expiration in minutes. Once the OAuthApplicationCredential is created, you can to access the token information by calling getTokenInfo() on the credential.

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
        lifecycleScope.launch {
            val oAuthApplicationCredential = OAuthApplicationCredential.create(
                portalUrl = "portalUrl",
                clientId = "clientId",
                clientSecret = "clientSecret",
                tokenExpirationInterval = 30
            ).getOrNull() ?: return@launch

            val oAuthApplicationTokenInfo = oAuthApplicationCredential.getTokenInfo().getOrThrow()

            ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler =
                ArcGISAuthenticationChallengeHandler {
                    ArcGISAuthenticationChallengeResponse.ContinueWithCredential(oAuthApplicationCredential)
                }
        }

Network credentials

You can access resources secured by network authentication using the following credential types:

• PasswordCredential - A credential object that is used to authenticate HTTP Basic or Integrated Windows Authentication (IWA) secured resources.
• CertificateCredential - A credential object that is used to authenticate Public Key Infrastructure (PKI) secured resources.

PasswordCredential

The PasswordCredential is used to authenticate HTTP Basic or Integrated Windows Authentication (IWA) secured resources.

1
var passwordCredential = PasswordCredential("username", "password")

CertificateCredential

CertificateCredential represents a digital client certificate used to access certificate secured resources. All digital certificates need to be pre-installed in the device keychain. The CertificateCredential can be created using the alias of the chosen certificate.

1
2
3
4
5
6
7
8
9
10
11
private suspend fun showCertificatePicker(activityContext: Activity): String? =
    suspendCancellableCoroutine { continuation ->
        val aliasCallback = KeyChainAliasCallback { alias ->
            continuation.resume(alias)
        }
        KeyChain.choosePrivateKeyAlias(
            activityContext, aliasCallback, null, null, null, null
        )
}
val selectedAlias = showCertificatePicker(activityContext)
var certificateCredential = selectedAlias?.let { CertificateCredential(it) } ?: null