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
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
    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
   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
               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
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
    ArcGISEnvironment.authenticationManager.networkAuthenticationChallengeHandler =
        NetworkAuthenticationChallengeHandler { authenticationChallenge ->
            when (authenticationChallenge.networkAuthenticationType) {
                is NetworkAuthenticationType.UsernamePassword -> {
                    // Create the Password Credential
                    val credential = PasswordCredential("username", "password")
                    NetworkAuthenticationChallengeResponse.ContinueWithCredential(credential = credential)
                }

                is NetworkAuthenticationType.ClientCertificate -> {
                    val selectedAlias = showCertificatePicker(activityContext = activityContext)
                    selectedAlias?.let {
                        NetworkAuthenticationChallengeResponse.ContinueWithCredential(credential = CertificateCredential(it))
                    } ?: NetworkAuthenticationChallengeResponse.ContinueAndFail
                }

                is NetworkAuthenticationType.ServerTrust -> {
                    NetworkAuthenticationChallengeResponse.ContinueWithCredential(credential = ServerTrust)
                }
            }
        }

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
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
        val arcGISCredentialStore =
            ArcGISCredentialStore.createWithPersistence().getOrNull() ?: ArcGISCredentialStore().also {
                Log.w("Auth", "Persistent ArcGISCredentialStore unavailable; using in-memory store.")
            }

        ArcGISEnvironment.authenticationManager.arcGISCredentialStore = arcGISCredentialStore

        val networkCredentialStore =
            NetworkCredentialStore.createWithPersistence().getOrNull() ?: NetworkCredentialStore().also {
                Log.w("Auth", "Persistent NetworkCredentialStore unavailable; using in-memory store.")
            }

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
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
    val arcGISCredentialStore = ArcGISEnvironment.authenticationManager.arcGISCredentialStore

    val networkCredentialStore =
        ArcGISEnvironment.authenticationManager.networkCredentialStore

    scope.launch {
        arcGISCredentialStore.getCredentials().forEach {
            when {
                it is OAuthUserCredential -> {
                    it.revokeToken()
                }

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