Access services with OAuth credentials

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

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

Steps

Create OAuth credentials for user authentication

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

1. Go to the Create OAuth credentials for user authentication tutorial and create OAuth credentials using your ArcGIS Location Platform or ArcGIS Online account.

2. Copy the Client ID and Redirect URL as you will use them to implement user authentication later in this tutorial. The Client ID is found on the Application item's Overview page, while the Redirect URL is found on the Settings page.

Open an Android Studio project with Gradle

1. Open the project you created by completing the Display a map tutorial.

2. Continue with the following instructions to access the World Traffic Service using OAuth 2.0 and display it as a feature layer.

3. Modify the old project for use in this new tutorial.

   Expand for detailed instructions

   1. On your file system, delete the .idea folder, if present, at the top level of your project.

   2. In the Android view, open app > res > values > strings.xml.

      In the <string name="app_name"> element, change the text content to Access services with OAuth 2.0.

      strings.xml

      Use dark colors for code blocks

      1
      2
      3
      4
      5
      <resources>
      
          <string name="app_name">Access services with OAuth 2.0</string>
      
      </resources>

   3. In the Android view, open Gradle Scripts > settings.gradle.kts.

      Change the value of rootProject.name to "Access services with OAuth 2.0".

      settings.gradle.kts

      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
      dependencyResolutionManagement {
          repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
          repositories {
              google()
              mavenCentral()
              maven { url = uri("https://esri.jfrog.io/artifactory/arcgis") }
          }
      }
      
      rootProject.name = "Access services with OAuth 2.0"
      include(":app")

   4. Click File > Sync Project with Gradle files. Android Studio will recognize your changes and create a new .idea folder.

4. Open the app > kotlin+java > com.example.app > MainActivity.kt. Delete the code in the MainActivity class, leaving only the class declaration.

   MainActivity.kt

   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
   class MainActivity : ComponentActivity() {
   
   

Add imports

1. Open app > kotlin+java > com.example.app > screens > MainScreen.kt. Modify import statements to reference the packages and classes required for this tutorial.

   MainScreen.kt

   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
   @file:OptIn(ExperimentalMaterial3Api::class)
   
   package com.example.app.screens
   
   import androidx.compose.foundation.layout.fillMaxSize
   import androidx.compose.foundation.layout.padding
   import androidx.compose.material3.ExperimentalMaterial3Api
   import androidx.compose.material3.Scaffold
   import androidx.compose.material3.Text
   import androidx.compose.material3.TopAppBar
   import androidx.compose.runtime.Composable
   import androidx.compose.runtime.remember
   import androidx.compose.ui.Modifier
   import androidx.compose.ui.res.stringResource
   import com.arcgismaps.mapping.ArcGISMap
   import com.arcgismaps.mapping.BasemapStyle
   import com.arcgismaps.mapping.Viewpoint
   import com.arcgismaps.mapping.layers.ArcGISMapImageLayer
   import com.arcgismaps.toolkit.geoviewcompose.MapView
   import com.example.app.R
   
   

Add a traffic layer to the map

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 is a secure service and requires an ArcGIS Online organizational subscription.

1. In MainScreen.kt, create an ArcGISMapImageLayer to display the traffic service.

   MainScreen.kt

   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
   fun createMap(): ArcGISMap {
   
       // Create a layer to display the ArcGIS World Traffic service
       val trafficLayer = ArcGISMapImageLayer("https://traffic.arcgis.com/arcgis/rest/services/World/Traffic/MapServer")
   
       return ArcGISMap(BasemapStyle.ArcGISTopographic).apply {
           initialViewpoint = Viewpoint(
               latitude = 34.02700,
               longitude = -118.80543,
               scale = 72000.0
           )
   
       }
   }

2. Add the layer to the map's collection of data layers (operational layers).

   MainScreen.kt

   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
   fun createMap(): ArcGISMap {
   
       // Create a layer to display the ArcGIS World Traffic service
       val trafficLayer = ArcGISMapImageLayer("https://traffic.arcgis.com/arcgis/rest/services/World/Traffic/MapServer")
   
       return ArcGISMap(BasemapStyle.ArcGISTopographic).apply {
           initialViewpoint = Viewpoint(
               latitude = 34.02700,
               longitude = -118.80543,
               scale = 72000.0
           )
   
           operationalLayers.add(trafficLayer)
   
       }
   }

Integrate OAuth credentials into your app

The ArcGIS Maps SDK for Kotlin toolkit contains classes and composable functions that abstract some of the detail of implementing OAuth 2.0 authentication in your app.

First you will create an AuthenticatorState and then instantiate OAuthUserConfiguration and assign it to the AuthenticatorState.oAuthUserConfiguration property. You will need your OAuth Client ID and Redirect URL when you instantiate OAuthUserConfiguration.

Then you will call the DialogAuthenticator composable to display the a log-in screen.

1. In MainActivity.kt add an authenticator property to the MainActivity class.

   MainActivity.kt

   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
   class MainActivity : ComponentActivity() {
   
       private val authenticatorState = AuthenticatorState()
   
   
   

2. Add the onCreate() lifecycle method to the MainActivity class.

   MainActivity.kt

   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
   class MainActivity : ComponentActivity() {
   
       private val authenticatorState = AuthenticatorState()
   
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
   
           enableEdgeToEdge()
   
           setContent {
               TutorialTheme {
                   MainScreen()
   
               }
           }
       }
   }

3. In onCreate(), instantiate OAuthUserConfiguration, passing your clientId and your redirectUrl.

   MainActivity.kt

   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
   class MainActivity : ComponentActivity() {
   
       private val authenticatorState = AuthenticatorState()
   
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
   
           authenticatorState.oAuthUserConfiguration = OAuthUserConfiguration(
               portalUrl = "https://www.arcgis.com",
   
               clientId = "your_client_id",
               redirectUrl = "your_redirect_url"
           )
   
           enableEdgeToEdge()
   
           setContent {
               TutorialTheme {
                   MainScreen()
   
               }
           }
       }
   }
   More info on portalUrl

   The value of portalUrl in the code block is https://www.arcgis.com. Alternatively, it could be the URL of your ArcGIS Online organization. In both cases, the Android Custom Tab will display a log-in for the user's credentials.

   Note that any other values for portalUrl will result in a default log-in screen for the user credentials, which are then authenticated using ArcGIS token instead of OAuth. If you see the following screen in this tutorial, you are not being authenticated with OAuth. Verify the paramters you pass to the OAuthConfiguration constructor in MainActivity and the android:scheme and android:host attributes of the data element in AndroidManifest.xml.

   

4. Inside the TutorialTheme block, call the DialogAuthenticator composable, passing in authenticatorState.

   MainActivity.kt

   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
   class MainActivity : ComponentActivity() {
   
       private val authenticatorState = AuthenticatorState()
   
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
   
           authenticatorState.oAuthUserConfiguration = OAuthUserConfiguration(
               portalUrl = "https://www.arcgis.com",
   
               clientId = "your_client_id",
               redirectUrl = "your_redirect_url"
           )
   
           enableEdgeToEdge()
   
           setContent {
               TutorialTheme {
                   MainScreen()
   
                   DialogAuthenticator(authenticatorState)
   
               }
           }
       }
   }

5. Open app > manifests > AndroidManifest.xml and locate the <activity> tag for the OAuth user sign-in activity. The OAuthUserSignInActivity is defined in the ArcGIS Maps SDK for Kotlin toolkit.

   More info

   The OAuthUserSignInActivity class is an activity that launches a CustomTabs activity and receives the redirect intent that is sent when the user completes the CustomTabs prompt. For more information, see the README for the authentication component in the ArcGIS Maps SDK for Kotlin Toolkit.

6. The <data> element of OAuthUserSignInActivity has an android:scheme attribute and and android:host where you must specify the scheme and the host of your OAuth redirect URL. See Create OAuth credentials for user authentication above for details on redirect URL, scheme, and host.

   AndroidManifest.xml

   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
           <activity
               android:name="com.arcgismaps.toolkit.authentication.OAuthUserSignInActivity"
               android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
               android:exported="true"
               android:launchMode="singleTop" >
               <intent-filter>
                   <action android:name="android.intent.action.VIEW" />
   
                   <category android:name="android.intent.category.DEFAULT" />
                   <category android:name="android.intent.category.BROWSABLE" />
   
                   <data
                       android:scheme="your_redirect_url_scheme"
                       android:host="your_redirect_url_host" />
   
               </intent-filter>
           </activity>
   

   Expand

7. Click Run > Run > app to run the app.

When running your app, you will be prompted for username and password in an Android Custom Tab.

After successfully logging in with your ArcGIS Online credentials, you should see the map with the topographic basemap layer centered on the Santa Monica Mountains in California. You will also see the traffic layer, with its symbology of green, yellow, orange, and red roads to indicate current traffic flow. This is a secured layer, which is visible in your app because the user has entered valid ArcGIS Online username and password.

What's next?

Learn how to use additional API features, ArcGIS location services, and ArcGIS tools in these tutorials:

• Display a web map