Authenticate with an ArcGIS identity

Learn how to use ArcGIS API for Javascript to create an ArcGIS identity, also known as named user login.

If your application needs access to your users' secure content through ArcGIS or if you are distributing your app through ArcGIS Marketplace, you must implement authentication with an ArcGIS identity. This allows individual users with an ArcGIS Online or ArcGIS Enterprise account to authorize your app to use the content and services to which they have access; it also uses their credits for any paid premium content and services.

Prerequisites

You need an ArcGIS account to register a new application and obtain its client_id. See the register your application tutorial. If you do not have an ArcGIS account you can sign up for a free ArcGIS Developer account.

When registering your application you will need to configure a redirect URL that will point to the URL where you are hosting your application. Generally this will be a local web server such as http://localhost:8000.

Steps

Create a new pen

  1. Go to CodePen to create a new pen for your mapping application.

Add the HTML

  1. In Codepen > HTML, add HTML and CSS to create a page with <button> and <pre> elements to allow the user to sign in, sign out, and to display user credentials.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    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
    <html>
    
    <head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
      <meta name="viewport" content="initial-scale=1, maximum-scale=1,user-scalable=no" />
      <title>ArcGIS API for JavaScript Tutorials: Authenticate with an ArcGIS identity</title>
    
    
      <style>
        html,
        body {
          font-size: 150%;
          margin: 10vh 10vw;
        }
      </style>
    
    </head>
    
    <body>
    
      <button id="sign-in" class="btn btn-primary">Sign In</button>
      <button id="sign-out" class="btn btn-primary">Sign Out</button>
      <pre><code id="results"></code></pre>
    
    </body>
    
    </html>

Reference the API

  1. In the <head> tag, add references to the CSS file and JS library.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.
    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
    <head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
      <meta name="viewport" content="initial-scale=1, maximum-scale=1,user-scalable=no" />
      <title>ArcGIS API for JavaScript Tutorials: Authenticate with an ArcGIS identity</title>
    
    
      <link rel="stylesheet" href="https://js.arcgis.com/4.25/esri/themes/light/main.css">
      <script src="https://js.arcgis.com/4.25/"></script>
    
      <style>
        html,
        body {
          font-size: 150%;
          margin: 10vh 10vw;
        }
      </style>
    
    </head>
    
    Expand

Add modules

  1. In the <head> tag, add a <script> tag and a require statement to load the Portal, OAuthInfo, and IdentityManager modules.

    The ArcGIS API for JavaScript is available as AMD modules and ES modules, but this tutorial is based on AMD. The AMD require function uses references to determine which modules will be loaded – for example, you can specify "esri/Map" for loading the Map module. After the modules are loaded, they are passed as parameters (e.g. Map) to the callback function where they can be used in your application. It is important to keep the module references and callback parameters in the same order. For more information on the different types of modules, visit the Introduction to Tooling guide topic.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    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
      <script>
    
        require([
          "esri/portal/Portal",
          "esri/identity/OAuthInfo",
          "esri/identity/IdentityManager"
        ], function (Portal, OAuthInfo, esriId) {
    
        });
      </script>
    
    Expand

Register credentials with Identity Manager

  1. From the ArcGIS Developer dashboard, OAuth 2.0 tab, copy your application's client_id.

  2. Create an OAuthInfo object and set the appId with the copied client_id before you register it with IdentityManager.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.Add line.Add line.Add line.
    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
        require([
          "esri/portal/Portal",
          "esri/identity/OAuthInfo",
          "esri/identity/IdentityManager"
        ], function (Portal, OAuthInfo, esriId) {
    
          const info = new OAuthInfo({
            appId: "YOUR-CLIENT-ID",
            popup: false // the default
          });
          esriId.registerOAuthInfos([info]);
    
    Expand

Handle sign in

Once you have registered your client_id with IdentityManager the ArcGIS API for JavaScript will automatically prompt a user to authorize your application whenever it accesses a service that requires authentication. Create a sign in experience by accessing the users profiles with the Portal class.

  1. Create a handleSignedIn function to be called when the user authorizes your application and then load the Portal. After the user provides authorization, obtain and display the fullName and username on the page.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    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
          const info = new OAuthInfo({
            appId: "YOUR-CLIENT-ID",
            popup: false // the default
          });
          esriId.registerOAuthInfos([info]);
    
          function handleSignedIn() {
    
            const portal = new Portal();
            portal.load().then(() => {
              const results = { name: portal.user.fullName, username: portal.user.username };
              document.getElementById("results").innerText = JSON.stringify(results, null, 2);
            });
    
          }
    
    
    Expand
  2. Call the checkSignInStatus method against a service URL. If the user has provided credentials, call the handleSignedIn function.

    checkSignInStatus can accept a URL for any service. The default ArcGIS portal URL https://arcgis.com/sharing/rest/ is the easiest way to fully authenticate a user.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.Add line.Add line.Add line.Add line.
    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
          const info = new OAuthInfo({
            appId: "YOUR-CLIENT-ID",
            popup: false // the default
          });
          esriId.registerOAuthInfos([info]);
    
          esriId
            .checkSignInStatus(info.portalUrl + "/sharing")
            .then(() => {
              handleSignedIn();
            })
    
          function handleSignedIn() {
    
            const portal = new Portal();
            portal.load().then(() => {
              const results = { name: portal.user.fullName, username: portal.user.username };
              document.getElementById("results").innerText = JSON.stringify(results, null, 2);
            });
    
          }
    
    
    Expand

Handle sign out

  1. Create a handleSignedOut function when a user's credentials are destroyed.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.Add line.
    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
          function handleSignedIn() {
    
            const portal = new Portal();
            portal.load().then(() => {
              const results = { name: portal.user.fullName, username: portal.user.username };
              document.getElementById("results").innerText = JSON.stringify(results, null, 2);
            });
    
          }
    
          function handleSignedOut() {
            document.getElementById("results").innerText = 'Signed Out'
          }
    
    Expand
  2. Append a catch statement to call the handleSignedOut function when the user signs out.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.
    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
          esriId
            .checkSignInStatus(info.portalUrl + "/sharing")
            .then(() => {
              handleSignedIn();
            })
    
            .catch(() => {
              handleSignedOut();
    
            });
    
    Expand

Add event listeners

  1. Call the getCredential method when a user clicks the sign-in button.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.Add line.Add line.
    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
            .catch(() => {
              handleSignedOut();
    
            });
    
          document.getElementById("sign-in").addEventListener("click", function () {
            esriId.getCredential(info.portalUrl + "/sharing");
          });
    
    
    Expand
  2. Call the destroyCredentials method when a user clicks the sign-out button before reloading the page.

    Expand
    Use dark colors for code blocks
                                                                                       
    Add line.Add line.Add line.Add line.
    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
            .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();
          });
    
    Expand

Run the App

You should now have an application that can check for credentials using OAuth 2.0.

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