Access services with OAuth 2.0

Learn how to authenticate a user to access a secure ArcGIS service with OAuth 2.0.

access services with oauth 2

In this tutorial, you will build an app that uses named user login credentials to access a secure ArcGIS service using OAuth 2.0.

You can use different authentication methods to access ArcGIS location services. To implement OAuth 2.0, you can use your ArcGIS account to register an application and get a client ID, and then configure your app to redirect users to login with their credentials when the service or content is accessed. This is known as "named user" or ArcGIS identity authentication. If the app uses premium services that consume credits, the app user's account will be charged.

You will implement OAuth 2.0 so users can sign in to ArcGIS to access the ArcGIS World Traffic service.

Prerequisites

The following are required for this tutorial:

  1. An ArcGIS account to access your API keys. If you don't have an account, sign up for free.
  2. Confirm that your system meets the minimum system requirements.
  3. An IDE for Java.

Steps

Configure OAuth 2.0 for your app

Use the ArcGIS Developer dashboard to create an application, generate a client ID, and define a redirect URL to access secure services.

  1. Sign in to your ArcGIS developer account. If you don't already have one, sign-up for free. You need to sign in so you can create an application and get a client ID for authentication.
  2. Click the OAuth 2.0 tab in the ribbon at the top.
  3. Click the New Application button in the upper-left of the page.
  4. In the Create New Application window, provide a Name and an optional Description for your application definition. Then click Create application. When the application is created, Client ID, Client Secret, and Temporary Token values will also be generated.
  5. Click the Add URI button at the bottom of the page to add a redirect URL.
  6. In the Add Allowed URI window, type my-app://auth and click Add.
You'll use the `client ID` and `redirect URL` when implementing OAuth in your app's code.

The client ID uniquely identifies your app on the authenticating server. If the server cannot find an app with the provided client ID, it will not proceed with authentication.

The redirect URL is used to identify a response from the authenticating server when the system returns control back to your app after an OAuth 2.0 login. You can configure several redirect URLs in your application definition and can remove or edit them. It's important to make sure the redirect URL used in your app's code matches a redirect URL configured for the application.

A temporary token can be used to test access to secure resources without having to implement the full OAuth workflow.

The client secret is only needed in some OAuth workflows and will not be used in this tutorial.

Open a Java project with Gradle

  1. To start this tutorial, complete the Display a map tutorial, or download and unzip the Display a map solution into a new folder.

  2. Open the build.gradle file as a project in IntelliJ IDEA.

  3. If you downloaded the solution project, set your API key.

    An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.

    1. Go to your developer dashboard to get your API key. For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.

    2. In the IntelliJ IDEA > Project tool window, open src/main/java/com.example.app and click App.

    3. In the start() method, set the API key property on the ArcGISRuntimeEnvironment with your API key. Replace YOUR_API_KEY with your actual API Key. Be sure to surround your API Key with quotes, because the parameter passed to setApiKey is a string.

      App.java
      Use dark colors for code blocks
                                                                                   
      Change lineChange lineChange lineChange 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
        @Override
        public void start(Stage stage) {
          // set the title and size of the stage and show it
          stage.setTitle("Display a map tutorial");
          stage.setWidth(800);
          stage.setHeight(700);
          stage.show();
      
          // create a JavaFX scene with a stack pane as the root node, and add it to the scene
          StackPane stackPane = new StackPane();
          Scene scene = new Scene(stackPane);
          stage.setScene(scene);
      
          // Note: it is not best practice to store API keys in source code.
          // The API key is referenced here for the convenience of this tutorial.
          String yourApiKey = "YOUR_API_KEY";
          ArcGISRuntimeEnvironment.setApiKey(yourApiKey);
      

Prepare files before coding the app

Modify the files from the Display a map tutorial so they can be used in this tutorial: you will add imports, change the application title, and modify the view point's scale. You will then add required JavaFX controls to the build configuration.

  1. In IntellJ IDEA, locate the Project tool window, open src/main/java/com.example.app, and click App. Add the following imports, replacing those from the Display a map tutorial.

    1. In the main menu of IntelliJ IDEA, click View > Tool Windows > Project. The Project Tool window displays, with a vertical tab on the left that says Project.

    2. Inside the Project tool window, your view name should also be Project. If the view name is something else (such as Packages or Project Files), click on the leftmost control in the title bar of the Project tool window, and select Project from the drop-down list.

    Project view in Project tool window

    App.java
    Use dark colors for code blocks
                                                                                                                 
    Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange 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
    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
    package com.example.app;
    
    import com.esri.arcgisruntime.ArcGISRuntimeEnvironment;
    import javafx.application.Application;
    import javafx.scene.Scene;
    import javafx.scene.layout.StackPane;
    import javafx.stage.Stage;
    
    import com.esri.arcgisruntime.layers.ArcGISMapImageLayer;
    import com.esri.arcgisruntime.mapping.ArcGISMap;
    import com.esri.arcgisruntime.mapping.BasemapStyle;
    import com.esri.arcgisruntime.mapping.Viewpoint;
    import com.esri.arcgisruntime.mapping.view.MapView;
    import com.esri.arcgisruntime.security.AuthenticationManager;
    import com.esri.arcgisruntime.security.DefaultAuthenticationChallengeHandler;
    import com.esri.arcgisruntime.security.OAuthConfiguration;
    
    public class App extends Application {
    
  2. In the start() lifecycle method, change the title that will appear on the application window to Access services with OAuth 2.0.

    App.java
    Use dark colors for code blocks
                                                                                                                 
    Change lineChange 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
    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
      @Override
      public void start(Stage stage) {
    
        try {
    
          // set title, size, and add scene to stage
          stage.setTitle("Access services with OAuth 2.0");
    
          stage.setWidth(800);
          stage.setHeight(700);
          stage.show();
    
  3. Change the scale of the map's initial viewpoint to 72000. This scale will make the secured layer visible without zooming in.

    App.java
    Expand
    Use dark colors for code blocks
                                                                                                                 
    Change 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
    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
          ArcGISMap map = new ArcGISMap(BasemapStyle.ARCGIS_TOPOGRAPHIC);
    
          // set the map on the map view
          mapView.setMap(map);
    
          mapView.setViewpoint(new Viewpoint(34.02700, -118.80543, 72000.0 ));
    
    Expand
  4. In the Project tool window, click build.gradle. Add two JavaFX modules: `'javafx.fxml' and 'javafx.web'. These modules are required by the OAuth code that you will add shortly.

    build.gradle
    Expand
    Use dark colors for code blocks
                                                   
    Change 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
    javafx {
        version = "17.0.2"
    
        modules = [ 'javafx.controls', 'javafx.fxml', 'javafx.web' ]
    
    }
    
    Expand

Implement OAuth 2.0 authentication

ArcGIS Runtime provides an API that abstracts some of the details for OAuth 2.0 authentication in your app. You can use classes like AuthenticationManager to request, store, and manage credentials for secure resources.

Add code to set up the AuthenticationManager, which launches a small browser window titled Authentication Required. The user must enter log-in credentials before proceeding.

  1. In the start() method, after the line that calls mapView.setViewpoint(), create an OAuthConfiguration.

    App.java
    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
    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
          mapView.setViewpoint(new Viewpoint(34.02700, -118.80543, 72000.0 ));
    
          // set up an oauth config with url to portal, a client id and a re-direct url
          OAuthConfiguration oAuthConfiguration = new OAuthConfiguration("YOUR_ORGANIZATION_URL", "YOUR_CLIENT_ID", "YOUR_REDIRECT_URL");
    
    
    Expand

    The OAuthConfiguration constructor takes three parameters:

    • "YOUR_ORGANIZATION_URL": the URL for the ArcGIS Online organization that is associated with the developer account you used in Configure OAuth 2.0 for your app above. The format of the URL will be something like: https://www.myfirstname-mylastname.maps.arcgis.com.

    • "YOUR_CLIENT_ID": the Client ID from your OAuth 2.0 configuration.

    • "YOUR_REDIRECT_URI": the Redirect URI from your OAuth 2.0 configuration.

  2. Create a DefaultAuthenticationChallengeHandler and set it on the AuthenticationManager. Then add the oAuthConfiguration to the AuthenticationManager.

    App.java
    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
    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
          mapView.setViewpoint(new Viewpoint(34.02700, -118.80543, 72000.0 ));
    
          // set up an oauth config with url to portal, a client id and a re-direct url
          OAuthConfiguration oAuthConfiguration = new OAuthConfiguration("YOUR_ORGANIZATION_URL", "YOUR_CLIENT_ID", "YOUR_REDIRECT_URL");
    
          // set up the authentication manager to handle authentication challenges
          DefaultAuthenticationChallengeHandler defaultAuthenticationChallengeHandler = new DefaultAuthenticationChallengeHandler();
          AuthenticationManager.setAuthenticationChallengeHandler(defaultAuthenticationChallengeHandler);
          // add the OAuth configuration
          AuthenticationManager.addOAuthConfiguration(oAuthConfiguration);
    
    Expand
  3. Create a file named style.css to specify the visual display of the Authentication Required browser window.

    1. In the Project tool window, open src -> main and right-click the resources folder. In the context menu, click New -> File and name the file style.css.

    2. Copy the code displayed below and paste it into the style.css file.

      style.css
      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
      
      .panel-region .label {
        -fx-text-fill: white;
      }
      
      .label {
        -fx-text-fill: black;
      }
      
      .slider .axis {
          -fx-tick-label-fill: white;
      }
      
      .range-slider .axis {
          -fx-tick-label-fill: white;
      }
      
      .panel-region .check-box {
         -fx-text-fill: white;
      }
      
      .panel-region .radio-button {
         -fx-text-fill: white;
      }
      
      .color-picker .color-picker-label {
         -fx-text-fill: black;
      }
      

Add a traffic layer

You will add a layer to display the ArcGIS World Traffic service, a dynamic map service that presents historical and near real-time traffic information for different regions in the world. This service requires an ArcGIS Online organizational subscription.

ArcGIS World Traffic service data is updated every five minutes to provide traffic speed and traffic incident visualization and identification.

Traffic speeds are displayed as a percentage of free-flow speeds, which is frequently the speed limit or how fast cars tend to travel when unencumbered by other vehicles. The streets are color coded as follows:

  • Green (fast): 85 - 100% of free flow speeds
  • Yellow (moderate): 65 - 85%
  • Orange (slow); 45 - 65%
  • Red (stop and go): 0 - 45%
  1. Create an ArcGISMapImageLayer to display the traffic service. Then add the layer to the map's collection of data layers (operational layers).

    App.java
    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
    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
          // set up an oauth config with url to portal, a client id and a re-direct url
          OAuthConfiguration oAuthConfiguration = new OAuthConfiguration("YOUR_ORGANIZATION_URL", "YOUR_CLIENT_ID", "YOUR_REDIRECT_URL");
    
          // set up the authentication manager to handle authentication challenges
          DefaultAuthenticationChallengeHandler defaultAuthenticationChallengeHandler = new DefaultAuthenticationChallengeHandler();
          AuthenticationManager.setAuthenticationChallengeHandler(defaultAuthenticationChallengeHandler);
          // add the OAuth configuration
          AuthenticationManager.addOAuthConfiguration(oAuthConfiguration);
    
          ArcGISMapImageLayer trafficLayer = new ArcGISMapImageLayer("https://traffic.arcgis.com/arcgis/rest/services/World/Traffic/MapServer");
          map.getOperationalLayers().add(trafficLayer);
    
    Expand
  2. Run the app.

    Ensure to run the app as a Gradle task and not as an application in your IDE. In the Gradle tool window, under Tasks > application, click run.

You should initially see the map with the topographic basemap layer centered on the Santa Monica Mountains in California. You will then be prompted for an ArcGIS Online username and password. After you authenticate successfully with ArcGIS Online, the traffic layer will appear in the map.

ArcGIS World Traffic service layer

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