Access services with OAuth 2.0

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

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 types of authentication 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 user 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

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 authenticate-with-oauth://auth and click Add URI.

You'll use the client ID and redirect URL when implementing OAuth in your app's code.

Open an Android Studio project with Gradle

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

2. Modify the old project for use in this new tutorial. Expand More info for instructions.

   More info

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

   2. In the Android tool window, 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
      6
      7
      8
      9
      <resources>
      
          <string name="app_name">Access services with OAuth 2.0</string>
      
          <string name="oauth_client_id">YOUR_CLIENT_ID</string>
          <string name="oauth_redirect_uri_scheme">authenticate-with-oauth</string>
          <string name="oauth_redirect_uri_host">auth</string>
      
      </resources>

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

   4. The UI theme composable in Display a map tutorial was DisplayAMapTheme. Rename the theme composable throughout the tutorial by refactoring DisplayAMapTheme.

      In the Android tool window, open app > kotlin+java > com.exmple.app > ui.theme > Theme.kt.

      Right-click the function name DisplayAMapTheme and select Refactor -> Rename. Replace the name with AccessServicesWithOAuthTheme.

      Theme.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
      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
      @Composable
      fun DisplayAMapTheme(
      
          darkTheme: Boolean = isSystemInDarkTheme(),
          // Dynamic color is available on Android 12+
          dynamicColor: Boolean = true,
          content: @Composable () -> Unit
      ) {
          val colorScheme = when {
              dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
                  val context = LocalContext.current
                  if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
              }
      
              darkTheme -> DarkColorScheme
              else -> LightColorScheme
          }
      

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

3. Delete the code that sets your API key. Since your app will be using OAuth, you will not need an API Key.

   MainActivity.kt

   Expand

   Use dark colors for code blocks

   10 10 10 10 10 10 10 10 10 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

   Remove lineRemove lineRemove lineRemove lineRemove lineRemove 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
   class MainActivity : ComponentActivity() {
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
   
           setApiKey()
   
           setContent {
               DisplayAMapTheme {
                   MainScreen()
               }
           }
   
       }
   
       private fun setApiKey() {
   
           ArcGISEnvironment.apiKey = ApiKey.create("YOUR_API_KEY")
   
       }
   
   }

Prepare files before coding the app

Modify the files from the Display a map tutorial for use in this tutorial: you will replace import statements, define strings for OAuth client ID, redirect URI scheme, redirect URI HTMLOListElement, and add an Android activity for OAuth user sign-in.

1. In the Android tool window, open Gradle Scripts > build.gradle.kts (Module: app) and add a dependency on the authentication component defined in the ArcGIS Maps SDK for Kotlin Toolkit.

   build.gradle.kts (:app)

   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
   dependencies {
       implementation("androidx.core:core-ktx:1.12.0")
       implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
       implementation("androidx.activity:activity-compose:1.8.2")
       // Jetpack Compose Bill of Materials
       implementation(platform("androidx.compose:compose-bom:2023.10.01"))
       // Jetpack Compose dependencies
       implementation("androidx.compose.ui:ui")
       implementation("androidx.compose.material3:material3")
       // ArcGIS Map Kotlin SDK dependencies
       implementation("com.esri:arcgis-maps-kotlin:200.4.0")
       // Toolkit dependencies
       implementation(platform("com.esri:arcgis-maps-kotlin-toolkit-bom:200.4.0"))
       implementation("com.esri:arcgis-maps-kotlin-toolkit-geoview-compose")
   
       implementation("com.esri:arcgis-maps-kotlin-toolkit-authentication")
   
   }

2. Open app > kotlin+java > com.example.app > MainScreen.kt. Replace the import statements with the imports needed 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
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   @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.httpcore.authentication.OAuthUserConfiguration
   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.authentication.Authenticator
   import com.arcgismaps.toolkit.authentication.AuthenticatorState
   import com.arcgismaps.toolkit.geoviewcompose.MapView
   import com.example.app.R
   
   

3. Open app > res > values > strings.xml. Enter certain values that you specified while creating your OAuth configuration in Configure OAuth 2.0 for your app above.

   To find these values, log in to the Dashboard with your developer account, click the OAuth 2.0 tab, scroll to the OAuth configuration you created (It will have a name such as "Access Services OAuth2".) and click View Full Credentials.

   In string.xml define strings for the OAuth client ID, the redirect URI scheme, and the redirect URI host. Values are not quoted.

   • oauth_client_id: Replace the placeholder YOUR_CLIENT_ID with the Client ID that you defined for your app.

   • oauth_redirect_uri_scheme: The scheme of the redirect URI you defined for your app. This value is authenticate-with-oauth if you followed the suggestions in Configure OAuth 2.0 for your app.

   • oauth_redirect_uri_host: The host of the redirect URI that you defined for your app. This value is auth if you followed the suggestions in Configure OAuth 2.0 for your app.

   strings.xml

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   <resources>
   
       <string name="app_name">Access services with OAuth 2.0</string>
   
       <string name="oauth_client_id">YOUR_CLIENT_ID</string>
       <string name="oauth_redirect_uri_scheme">authenticate-with-oauth</string>
       <string name="oauth_redirect_uri_host">auth</string>
   
   </resources>

4. Open app > manifests > AndroidManifest.xml. Add an <activity> tag that declares the OAuth user sign-in activity. Note the <data> element that references the Redirect URI scheme and host.

   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.

   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
           <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="@string/oauth_redirect_uri_scheme"
                       android:host="@string/oauth_redirect_uri_host" />
               </intent-filter>
           </activity>
   

   Expand

Implement OAuth 2.0 authentication

The composable function Authenticator abstracts some details of OAuth 2.0 authentication in your app.

Calling AuthenticatorState requires that you pass an AuthenticatorState, which has an oAuthUserConfiguration property. Use your OAuth client ID and redirect URI to instantiate OAuthUserConfiguration.

1. Create oAuthClientId, oAuthRedirectUriScheme, and oAuthRedirectUriHost variables, using string resources defined in strings.xml.

   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
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   @Composable
   fun MainScreen() {
   
       val oAuthClientId = stringResource(id = R.string.oauth_client_id)
       val oAuthRedirectUriScheme = stringResource(id = R.string.oauth_redirect_uri_scheme)
       val oAuthRedirectUriHost = stringResource(id = R.string.oauth_redirect_uri_host)
   
       val map = remember {
           createMap()
       }
       Scaffold(
           topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
       ) {
           MapView(
               modifier = Modifier.fillMaxSize().padding(it),
               arcGISMap = map
           )
       }
   
   }
   

   Expand

2. Create a variable named oAuthRedirectUri that is initialized as the string concatenation of the Redirect URI scheme, the separator "://", and the Redirect URI host.

   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
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   @Composable
   fun MainScreen() {
   
       val oAuthClientId = stringResource(id = R.string.oauth_client_id)
       val oAuthRedirectUriScheme = stringResource(id = R.string.oauth_redirect_uri_scheme)
       val oAuthRedirectUriHost = stringResource(id = R.string.oauth_redirect_uri_host)
   
       val oAuthRedirectUri = oAuthRedirectUriScheme + "://" + oAuthRedirectUriHost
   
       val map = remember {
           createMap()
       }
       Scaffold(
           topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
       ) {
           MapView(
               modifier = Modifier.fillMaxSize().padding(it),
               arcGISMap = map
           )
       }
   
   }
   

   Expand

3. Inside a remember block, create an instance of AuthenticatorState, which is from the authentication component of ArcGIS Maps SDK for Kotlin Toolkit. Then set the oAuthUserConfiguration property by instantiating OAuthUserConfiguration and passing portalUrl, clientId, and redirectURL. Last, assign the remember { } call to a local variable named authenticatorState.

   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
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   @Composable
   fun MainScreen() {
   
       val oAuthClientId = stringResource(id = R.string.oauth_client_id)
       val oAuthRedirectUriScheme = stringResource(id = R.string.oauth_redirect_uri_scheme)
       val oAuthRedirectUriHost = stringResource(id = R.string.oauth_redirect_uri_host)
   
       val oAuthRedirectUri = oAuthRedirectUriScheme + "://" + oAuthRedirectUriHost
   
       val authenticatorState = remember {
           AuthenticatorState().apply {
               oAuthUserConfiguration = OAuthUserConfiguration(
                   portalUrl = "https://www.arcgis.com",
                   clientId = oAuthClientId,
                   redirectUrl = oAuthRedirectUri
               )
           }
       }
   
       val map = remember {
           createMap()
       }
       Scaffold(
           topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
       ) {
           MapView(
               modifier = Modifier.fillMaxSize().padding(it),
               arcGISMap = map
           )
       }
   
   }
   

   Expand

4. Call the Authenticator composable, passing authenticatorState. The Authenticator composable function should be called from the root level of your UI, typically from you MainScreen, to ensure that authentication prompts always appear on top of any other UI of your application.

   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
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   @Composable
   fun MainScreen() {
   
       val oAuthClientId = stringResource(id = R.string.oauth_client_id)
       val oAuthRedirectUriScheme = stringResource(id = R.string.oauth_redirect_uri_scheme)
       val oAuthRedirectUriHost = stringResource(id = R.string.oauth_redirect_uri_host)
   
       val oAuthRedirectUri = oAuthRedirectUriScheme + "://" + oAuthRedirectUriHost
   
       val authenticatorState = remember {
           AuthenticatorState().apply {
               oAuthUserConfiguration = OAuthUserConfiguration(
                   portalUrl = "https://www.arcgis.com",
                   clientId = oAuthClientId,
                   redirectUrl = oAuthRedirectUri
               )
           }
       }
   
       val map = remember {
           createMap()
       }
       Scaffold(
           topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
       ) {
           MapView(
               modifier = Modifier.fillMaxSize().padding(it),
               arcGISMap = map
           )
       }
   
       Authenticator(authenticatorState = authenticatorState)
   
   }
   

   Expand

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

1. 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
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   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)
   
       }
   }

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
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   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)
   
       }
   }

3. 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.