Access services with OAuth credentials

Learn how to implement user authentication to access a secure ArcGIS service with OAuth credentials.

access services with oauth 2

You can use different types of authentication to access secured ArcGIS services. To implement OAuth credentials for user authentication, you can use your ArcGIS account to register an app with your portal 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 user authentication. If the app uses premium ArcGIS Online services that consume credits, for example, the app user's account will be charged.

In this tutorial, you will build an app that implements user authentication using OAuth credentials so users can sign in and be authenticated through ArcGIS Online to access the ArcGIS World Traffic service.

Prerequisites

Before starting this tutorial:

  1. You need an ArcGIS Location Platform or ArcGIS Online account.

  2. Confirm that your system meets the minimum system requirements.

  3. An IDE for Java.

Steps

Create OAuth credentials

OAuth credentials are required to implement user authentication. These credentials are created as an Application item in your organization's portal.

  1. Sign in to your portal.

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

  3. In the Create developer credentials window, select OAuth 2.0 credentials radio button and click Next.

  4. Add a Redirect URL to your OAuth credentials: my-app://auth. The remaining properties, Referrer URLs, Application environment and URL, can remain with their default values. Click Next.

  5. For Privileges, click Next. Privileges are not required for this tutorial.

  6. Click Skip to move past Grant item access as it is not required for this tutorial.

  7. Provide a Title of your choice. Optionally, stipulate a Folder to store your Application item, add Tags, and add a Summary. Click Next.

  8. Review your settings and go back to correct any errors. When you are ready, click Create. When the application item is created, Client ID, Client Secret, and Temporary Token values will also be generated. You will be redirected to the Application item's Overview page.

You'll use the Client ID and Redirect URL when implementing OAuth in your app's code. The Client ID is found on the Application item's Overview page, while the Redirect URL is found on the Settings page.

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. Delete the code that sets your access token. Since your app will be using OAuth, you will not need an access token.

    App.java
    Use dark colors for code blocks
    49
    Remove 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
        ArcGISRuntimeEnvironment.setApiKey("YOUR_ACCESS_TOKEN");
    

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.

    App.java
    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
    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() life cycle 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
    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
      @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
    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
          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
    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 user authentication using OAuth credentials

ArcGIS Runtime provides an API that abstracts some of the details for user authentication using OAuth 2.0 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
    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
          mapView.setViewpoint(new Viewpoint(34.02700, -118.80543, 72000.0 ));
    
          // set up an OAuth config with URL to portal, a Client ID and a Redirect URL
          OAuthConfiguration oAuthConfiguration = new OAuthConfiguration("YOUR-ORGANIZATION-URL", "YOUR-APP-CLIENT-ID", "YOUR-APP-REDIRECT-URL");
    
    
    Expand
  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
    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
          mapView.setViewpoint(new Viewpoint(34.02700, -118.80543, 72000.0 ));
    
          // set up an OAuth config with URL to portal, a Client ID and a Redirect URL
          OAuthConfiguration oAuthConfiguration = new OAuthConfiguration("YOUR-ORGANIZATION-URL", "YOUR-APP-CLIENT-ID", "YOUR-APP-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
    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.

  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
    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
          // set up an OAuth config with URL to portal, a Client ID and a Redirect URL
          OAuthConfiguration oAuthConfiguration = new OAuthConfiguration("YOUR-ORGANIZATION-URL", "YOUR-APP-CLIENT-ID", "YOUR-APP-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.