Authorization code flow

The Authorization code flow is an OAuth 2.0OAuth 2.0 is an industry standard protocol for authorization. It defines how to obtain and manage credentials for web, desktop, and mobile applications. It is supported by ArcGIS.Learn more authorization method used to implement user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more in applications with a server-side component. This page provides an overview of the flow and explains how to implement it.

This is the recommended authentication flow for user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more in applications with a server-side component.

The Authorization code flow is an OAuth 2.0OAuth 2.0 is an industry standard protocol for authorization. It defines how to obtain and manage credentials for web, desktop, and mobile applications. It is supported by ArcGIS.Learn more workflow commonly used in apps with a server-side component. Authorization occurs in two steps, with the app first requesting an authorization codeAn authorization code is a string that is used to obtain an access token associated with a user account. It is required in user authentication flows that adhere to the OAuth2.0 authorization_code grant type.Learn more from the authorization endpointAn authorization endpoint is an ArcGIS portal service endpoint that can be queried to request an authorization code. It is used to implement user authentication OAuth2.0 flows.Learn more. The authorization code is then sent to the token endpointAn token endpoint is an endpoint of a portal service that can be queried to request an access token. It is used to implement user authentication OAuth2.0 flows.Learn more to request an access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more.

The general steps of how the Authorization code flow works are:

1. Application sends a request to the authorization endpointAn authorization endpoint is an ArcGIS portal service endpoint that can be queried to request an authorization code. It is used to implement user authentication OAuth2.0 flows.Learn more that includes a client_id and redirect_uri from OAuth credentialsOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential.Learn more.

2. The application user signs in with an ArcGIS accountAn ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription.Learn more. The authorization endpointAn authorization endpoint is an ArcGIS portal service endpoint that can be queried to request an authorization code. It is used to implement user authentication OAuth2.0 flows.Learn more verifies the user's identity and returns an authorization codeAn authorization code is a string that is used to obtain an access token associated with a user account. It is required in user authentication flows that adhere to the OAuth2.0 authorization_code grant type.Learn more.

3. Application uses the resulting authorization_code as well as the client_id and redirect_uri from OAuth credentialsOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential.Learn more, to submit a request to the token endpointAn token endpoint is an endpoint of a portal service that can be queried to request an access token. It is used to implement user authentication OAuth2.0 flows.Learn more. The token endpoint verifies the authorization code and issues an access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more.

4. Client uses the access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more to authorize requests to secure resourcesA secure resource is any item or service in an ArcGIS that requires an ArcGIS account and authentication to access. Examples include ArcGIS Location Services, and items and data services in an ArcGIS portal.Learn more.

Manual implementation

The remainder of this page shows how to manually implement user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more without using an ArcGIS APIAn ArcGIS API is a web, native, game engine, or scripting API that has advanced mapping and spatial analysis capabilities and can be used to access ArcGIS services. ArcGIS APIs are designed to work optimally with the ArcGIS system and provide the most advanced GIS features and the highest performance possible.Learn more or Maps SDKArcGIS Maps SDKs are developer products for building mapping and spatial analysis applications for web browsers, native devices, and game engines.Learn more. Instead, authentication is implemented by directly making HTTP requests to the proper REST APIArcGIS REST APIs are the API specifications for all ArcGIS location services and ArcGIS Enterprise services. They define the operations, parameters, and structures required to make HTTPS requests.Learn more endpoints.

This sample is written in JavaScript, but can be implemented in any language. It adheres to the OAuth 2.0 specification for the Authorization code flow.

Create OAuth credentials

User authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more requires a set of OAuth credentialsOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential.Learn more. These credentials are used to generate a client IDA Client ID is an identifier associated with an application that assists with client / server OAuth 2.0 authentication for ArcGIS client APIs.Learn more for your application and authorize redirect URLs. Please review the product and account requirements for user authentication prior to creation.

Configure authentication variables

1. Copy your client ID and chosen redirect URL from your OAuth credentialsOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential.Learn more and include them in your app.

   index.html

   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
           const clientId = '<YOUR_CLIENT_ID>';
           const redirectUri = '<YOUR_REDIRECT_URL>';
   
           let session = null;
           let map = null;
           const signInButton = document.getElementById('sign-in');
           const signOutButton = document.getElementById('sign-out');
   

Request an authorization code

1. Format a GET request to the authorization endpointAn authorization endpoint is an ArcGIS portal service endpoint that can be queried to request an authorization code. It is used to implement user authentication OAuth2.0 flows.Learn more. Include your client_id and redirect_uri.

   index.html

   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
           const authorizationEndpoint = 'https://www.arcgis.com/sharing/rest/oauth2/authorize' +
               '?client_id=' + clientId +
               '&redirect_uri=' + window.encodeURIComponent(redirectUri) +
               '&response_type=code' +
               '&expiration=20160';
   
   

2. When the user clicks 'sign in', open the authorization endpoint in a new window.

   index.html

   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
           const authorizationEndpoint = 'https://www.arcgis.com/sharing/rest/oauth2/authorize' +
               '?client_id=' + clientId +
               '&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'));
   

Create a callback

1. Create a callback function in index.html that will receive the authorization code.

   index.html

   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
           const oauthCallback = (authorizationCode) => {
   
           }
           window.oauthCallback = oauthCallback; //required due to the module scope of this script
   

2. Create a new HTML page at the location of your redirect URI. When a user successfully authenticates at the authorization endpoint, they will be redirected to this page.

   callback.html

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   
   <!DOCTYPE html>
     <head>
       <title>ArcGIS user authentication OAuth 2.0 callback (vanilla JS)</title>
     </head>
     <body>
       <script type="module">
   
       </script>
     </body>
   </html>

3. Access the authorization code returned from the endpoint. It is found in the search parameter of the URL. Pass the code to the callback function created in index.html.

   callback.html

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   
   <!DOCTYPE html>
     <head>
       <title>ArcGIS user authentication OAuth 2.0 callback (vanilla JS)</title>
     </head>
     <body>
       <script type="module">
   
           const match = (window.location.search) ? window.location.search.match(/\?code=([^&]+)/) : false;
           // if we found an authorization code in the URL, pass the token up to a global function in index.html
           if(match[1]) {
               window.opener.oauthCallback(match[1]);
           }
           window.close();
   
       </script>
     </body>
   </html>

Request an access token

1. Find the URL of the token endpointAn token endpoint is an endpoint of a portal service that can be queried to request an access token. It is used to implement user authentication OAuth2.0 flows.Learn more for your ArcGIS organizationAn organization a list of members from the same business, association, or entity who can sign in, access tools and applications, and collaborate with other members in a portal. All members have an ArcGIS account and are approved by an administrator to access the same portal.Learn more. For ArcGIS Online users, the token endpoint is https://www.arcgis.com/sharing/rest/oauth2/token.

   index.html

   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
           const oauthCallback = (authorizationCode) => {
   
               const tokenEndpoint = 'https://www.arcgis.com/sharing/rest/oauth2/token';
   
           }
           window.oauthCallback = oauthCallback; //required due to the module scope of this script
   

2. Submit an HTTP request to the token endpoint to request an access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more. Include your authorization_code, client_id, and redirect_uri to create a valid request, and set the grant_type as authorization_code.

   index.html

   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
           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
                   }),
                   headers: {
                       "Content-type": "application/json; charset=UTF-8"
                   }
               })
   
           }
           window.oauthCallback = oauthCallback; //required due to the module scope of this script
   

3. Access the response from the endpoint. If the request was valid, the response will contain an access_token, refresh_token, username, and other session information.

   index.html

   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
           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
                   }),
                   headers: {
                       "Content-type": "application/json; charset=UTF-8"
                   }
               })
   
                   .then(response => response.json()).then(newSession => {
                       updateSession(newSession);
                       initApp(newSession);
                   })
   
           }
           window.oauthCallback = oauthCallback; //required due to the module scope of this script
   

Serialize session info

1. Serialize the session information from the token endpoint and add it to local storage to make the session persistent across page refreshes.

   index.html

   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
           const updateSession = (sessionInfo) => {
               const userInfo = document.getElementById('user-info');
   
               if (!sessionInfo) {
                   localStorage.removeItem("__ARCGIS_USER_SESSION__");
                   session = null;
   
                   destroyApp();
   
                   // signed out sidebar state
                   userInfo.classList.add('hide');
                   userInfo.innerHTML = ``;
                   signOutButton.classList.add('hide');
                   signInButton.classList.remove('hide');
               }
   
               else {
                   session = sessionInfo;
                   localStorage.setItem("__ARCGIS_USER_SESSION__", JSON.stringify(session));
   
                   // signed in sidebar state
                   userInfo.classList.remove('hide');
                   userInfo.innerHTML = `Welcome, ${sessionInfo.username}.`;
                   signOutButton.classList.remove('hide');
                   signInButton.classList.add('hide');
               }
   
           }