Authorization code flow

The Authorization code flow is an OAuth 2.0 authorization method used to implement user authentication 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 authentication in applications with a server-side component.

The Authorization code flow is an OAuth 2.0 workflow commonly used in apps with a server-side component. Authorization occurs in two steps, with the app first requesting an authorization code from the authorization endpoint. The authorization code is then sent to the token endpoint to request an access token.

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

1. Application sends a request to the authorization endpoint that includes a client_id and redirect_uri from OAuth credentials.

2. The application user signs in with an ArcGIS account. The authorization endpoint verifies the user's identity and returns an authorization code.

3. Application uses the resulting authorization_code as well as the client_id and redirect_uri from OAuth credentials, to submit a request to the token endpoint. The token endpoint verifies the authorization code and issues an access token.

4. Client uses the access token to authorize requests to secure resources.

Manual implementation

The remainder of this page shows how to manually implement user authentication without using an ArcGIS API or Maps SDK. Instead, authentication is implemented by directly making HTTP requests to the proper REST API 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

A set of OAuth credentials are required for user authentication. These credentials are created as an item in your organization's portal.

Configure authentication variables

1. Copy your client ID and chosen redirect URL from your OAuth credentials 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
               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 endpoint. 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
               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
               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
               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 endpoint for your ArcGIS organization. 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
               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 token. 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
               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
               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
               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');
                   }
   
               }