How to implement user authentication

This topic outlines the high-level steps of how to implement user authentication.

1. Create OAuth credentials

User authentication requires a set of OAuth credentials.

The steps to create OAuth credentials with an ArcGIS Location Platform account are:

  1. Sign in to your ArcGIS portal.

  2. Click Content > My content > New item and select Developer credentials.

  3. Im the Credential types menu, select OAuth credentials.

  4. Add a redirect URL and click Next.

  5. In the Privileges and Grant item access menus, click Next; these are not required for user authentication.

  6. Name the credentials and click Next to review. When you are ready to create the credentials, click Create.

2. Implement an OAuth flow

Generic user authentication workflow
The typical user authentication. To view concrete examples, go to User authentication flows

The next step is to implement a user authentication flow by adding authentication code to your application. ArcGIS supports several different user authentication flows that you can implement, most of which adhere to the OAuth 2.0 specification.

The OAuth 2.0 Authorization code flow with PKCE is the recommended flow for all client-facing applications. This is the authorization flow used by ArcGIS Maps SDKs and scripting APIs.

ArcGIS APIs and SDKs

User authentication is typically implemented using an ArcGIS Maps SDK or a scripting API such as ArcGIS REST JS or the ArcGIS API for Python. These libraries make it easy to implement user authentication using the built-in AuthenticationManager and IdentityManager classes.

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for QtArcGIS REST JS
Expand
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
        const info = new OAuthInfo({
            appId: "YOUR_CLIENT_ID",
        });


        esriId.registerOAuthInfos([info]);
        esriId
            .checkSignInStatus(info.portalUrl + "/sharing")
            .then(() => {
                handleSignedIn();
            })
            .catch(() => {
                handleSignedOut();
            });

        document.getElementById("sign-in").addEventListener("click", function () {
            esriId.getCredential(info.portalUrl + "/sharing");
        });

        document.getElementById("sign-out").addEventListener("click", function () {
            esriId.destroyCredentials();
            window.location.reload();
        });
        let map;

Manual implementation

User authentication can also be implemented manually by making direct requests to the proper REST API endpoints. To do so, typically make a request to the authorization endpoint and token endpoint of your organization's portal service

This example shows how to implement an OAuth 2.0 authorization code flow with PKCE without an ArcGIS API.

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
163
164
165
166
167
168
169
170
            const authorizationEndpoint = 'https://www.arcgis.com/sharing/rest/oauth2/authorize'+
            '?client_id=' + clientId +
            '&code_challenge=' + codeChallenge +
            '&code_challenge_method=S256' +
            '&redirect_uri=' + window.encodeURIComponent(redirectUri)+
            '&response_type=code'+
            '&expiration=20160';

            signInButton.addEventListener('click', () => window.open(authorizationEndpoint, 'oauth-window', 'height=400,width=600,menubar=no,location=yes,resizable=yes,scrollbars=yes,status=yes'));

            signOutButton.addEventListener('click', () => updateSession(false));

            const oauthCallback = (authorizationCode) => {

                const tokenEndpoint = 'https://www.arcgis.com/sharing/rest/oauth2/token';

                fetch(tokenEndpoint, {
                    method:'POST',
                    body: JSON.stringify({
                        client_id:clientId,
                        grant_type:'authorization_code',
                        code:authorizationCode,
                        redirect_uri:redirectUri,
                        code_verifier:codeVerifier
                    }),
                    headers: {
                        "Content-type": "application/json; charset=UTF-8"
                    }
                })

Generate token flow

The generate token flow can be used in situations where it is not possible to implement secure OAuth 2.0 flows. This flow requests an access token by making a request to the /generateToken endpoint that includes an unencrypted username and password.

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
6
curl https://www.arcgis.com/sharing/rest/generateToken \
-d 'f=json' \
-d 'username=USERNAME' \
-d 'password=PASSWORD' \
-d 'referer=https://www.arcgis.com' \
-d 'client=referer'

3. Make a request

Implementing user authentication successfully will grant a unique access token to your application every time a user signs in. The access token will inherit the privileges of the signed-in user's ArcGIS account, granting it access to all of the secure resources the user's account has access to.

ArcGIS APIs and SDKs

If you use user authentication with an ArcGIS Maps SDK, the AuthenticationManager or IdentityManager classes automatically handle authentication with the access token, requiring no additional action from you.

The examples below show how to display a map in apps that implement user authentication.

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for Qt
Expand
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
        function handleSignedIn() {

            map = new Map({
                basemap: "arcgis/topographic" // basemap styles service
            });
            const view = new MapView({
                map: map,
                center: [-118.805, 34.027], // Longitude, latitude
                zoom: 13, // Zoom level
                container: "viewDiv" // Div element
            });

        }

ArcGIS REST APIs

If you implement user authentication manually, your application can include the access token in requests to REST APIs by setting the token parameter.

This example shows how to geocode an address with the geocoding service.

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
curl https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates \
-d "f=pjson" \
-d "address=1600 Pennsylvania Ave NW, DC" \
-d "token=<YOUR_ACCESS_TOKEN>"

Tutorials

Create OAuth credentials for user authentication

Create and configure OAuth credentials to set up user authentication.


Sign in with user authentication

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.