Access services with OAuth credentials

Learn how to implement user authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more to access a secure ArcGIS service A service, also known as an ArcGIS service, is software that supports an ArcGIS REST API and provides geospatial functionality or data. A service can be hosted by Esri or in ArcGIS Enterprise. Learn more with OAuth credentials OAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential. Learn more .

You can use different types of authentication to access secured ArcGIS services A service, also known as an ArcGIS service, is software that supports an ArcGIS REST API and provides geospatial functionality or data. A service can be hosted by Esri or in ArcGIS Enterprise. Learn more . To implement OAuth credentials for user authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more , you can use your ArcGIS account An ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription. Learn more to register an app with your portal ArcGIS portal, also known as a portal, is a website with applications and tools that can be used to create, manage, access, and share geospatial content and data. It supports security and authentication, developer credentials, content and data service management, user and group management, and site administration. A portal can be hosted in Esri's infrastructure or your own infrastructure. Learn more and get a Client ID A Client ID is an identifier associated with an application that assists with client / server OAuth 2.0 authentication for ArcGIS client APIs. Learn more , 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 ArcGIS Online is a GIS mapping, analytics, data hosting, and content management software as a service (SaaS) product. It includes applications, tools, APIs, and location services for users and developers. It is subscription-based and requires an ArcGIS Online account. Learn more services that consume credits Credits are the currency used by ArcGIS Online Organization accounts to account for data storage and location service consumption. Credits are consumed for specific transactions, such as accessing location services, and types of storage, such as storing features, performing analytics, and using premium content. Learn more , 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 OAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential. Learn more are required to implement user authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more . These credentials are created and stored as an Application item An item, also known as a content item, is a resource stored in a portal such as a web map, hosted layer, style, script tool, file, or notebook. Learn more in your organization’s portal ArcGIS portal, also known as a portal, is a website with applications and tools that can be used to create, manage, access, and share geospatial content and data. It supports security and authentication, developer credentials, content and data service management, user and group management, and site administration. A portal can be hosted in Esri's infrastructure or your own infrastructure. Learn more .

1. Go to the Create OAuth credentials for user authentication tutorial and create OAuth credentials OAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential. Learn more using your ArcGIS Location Platform An ArcGIS Location Platform account, formerly known as an ArcGIS Developer account, is an identity associated with an ArcGIS Location Platform subscription. Learn more or ArcGIS Online An ArcGIS Online account, also known as an ArcGIS Organization account, is an identity associated with an ArcGIS Online subscription. It can be used to access ArcGIS tools and develop applications with ArcGIS location services for an organization. Learn more account.

2. Copy the Client ID and Redirect URL as you will use them to implement user authentication User authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0. Learn more later in this tutorial. Both the Client ID and the Redirect URL are found on the Settings page.

More info about these OAuth properties

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 (also referred to as a callback url) is used to identify a response from the authenticating server when the system returns control back to your app after an OAuth login. Since it does not necessarily represent a valid endpoint that a user could navigate to, the redirect URL can use a custom scheme, such as my-app://. 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.

• The redirect URL consists of three parts:
  • the scheme
  • the separator string ”://”
  • the host
• Scheme: You are probably familiar with standard schemes used in internet URLs: http, https, ftp, etc. In OAuth 2.0, you can create a private-use URI scheme (also known as custom URL scheme), which will only be used by the authorization server and your app. This is an arbitrary string whose allowed characters are declared in the Uniform Resource Locators (URL) Spec . Though not strictly required, making your scheme unique is a good practice. Some organization use the app ID or the reverse domain of their company (com.mycompany.appname) as the URL scheme.
• Host: An arbitrary string occupying the host portion of the URL. It allows you to use the same URL scheme with different URL hosts.

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

      <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

      14 collapsed lines
      pluginManagement {
          repositories {
              google {
                  content {
                      includeGroupByRegex("com\\.android.*")
                      includeGroupByRegex("com\\.google.*")
                      includeGroupByRegex("androidx.*")
                  }
              }
              mavenCentral()
              gradlePluginPortal()
          }
      }
      
      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

   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

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

More info about the traffic service

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. In MainScreen.kt, create an ArcGISMapImageLayer to display the traffic service.

   MainScreen.kt

   37 collapsed lines
   @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
   
   @Composable
   fun MainScreen() {
   
       val map = remember {
           createMap()
       }
       Scaffold(
           topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
       ) {
           MapView(
               modifier = Modifier.fillMaxSize().padding(it),
               arcGISMap = map
           )
       }
   }
   
   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

   37 collapsed lines
   @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
   
   @Composable
   fun MainScreen() {
   
       val map = remember {
           createMap()
       }
       Scaffold(
           topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
       ) {
           MapView(
               modifier = Modifier.fillMaxSize().padding(it),
               arcGISMap = map
           )
       }
   }
   
   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. Then you will instantiate OAuthUserConfiguration, add the instance to a list, and assign the list to the AuthenticatorState.oAuthUserConfigurations 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.

More info

The DialogAuthenticator composable displays an Authentication UI when an authentication challenge is issued. The AuthenticatorState interface handles authentication challenges and exposes the state for the DialogAuthenticator to display to the user. Both are defined in the authentication component of the ArcGIS Maps SDK for Kotlin Toolkit.

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

   MainActivity.kt

   13 collapsed lines
   package com.example.app
   
   import android.os.Bundle
   import androidx.activity.ComponentActivity
   import androidx.activity.compose.setContent
   import androidx.activity.enableEdgeToEdge
   import com.arcgismaps.httpcore.authentication.OAuthUserConfiguration
   import com.arcgismaps.toolkit.authentication.AuthenticatorState
   import com.arcgismaps.toolkit.authentication.DialogAuthenticator
   import com.example.app.screens.MainScreen
   import com.example.app.ui.theme.TutorialTheme
   
   
   class MainActivity : ComponentActivity() {
   
       private val authenticatorState = AuthenticatorState()

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

   MainActivity.kt

   13 collapsed lines
   package com.example.app
   
   import android.os.Bundle
   import androidx.activity.ComponentActivity
   import androidx.activity.compose.setContent
   import androidx.activity.enableEdgeToEdge
   import com.arcgismaps.httpcore.authentication.OAuthUserConfiguration
   import com.arcgismaps.toolkit.authentication.AuthenticatorState
   import com.arcgismaps.toolkit.authentication.DialogAuthenticator
   import com.example.app.screens.MainScreen
   import com.example.app.ui.theme.TutorialTheme
   
   
   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

   13 collapsed lines
   package com.example.app
   
   import android.os.Bundle
   import androidx.activity.ComponentActivity
   import androidx.activity.compose.setContent
   import androidx.activity.enableEdgeToEdge
   import com.arcgismaps.httpcore.authentication.OAuthUserConfiguration
   import com.arcgismaps.toolkit.authentication.AuthenticatorState
   import com.arcgismaps.toolkit.authentication.DialogAuthenticator
   import com.example.app.screens.MainScreen
   import com.example.app.ui.theme.TutorialTheme
   
   
   class MainActivity : ComponentActivity() {
   
       private val authenticatorState = AuthenticatorState()
   
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
   
           authenticatorState.oAuthUserConfigurations = listOf(
               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 if the OAuth configuration does not match the portalUrl, a username/password prompt will be displayed instead; this will authenticate the user with ArcGIS token instead of OAuth. If you see the following screen in this tutorial, you are not being authenticated with OAuth. To troubleshoot your OAuth code, verify the parameters you’re passing to the OAuthUserConfiguration constructor in MainActivity and verify as well 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

   13 collapsed lines
   package com.example.app
   
   import android.os.Bundle
   import androidx.activity.ComponentActivity
   import androidx.activity.compose.setContent
   import androidx.activity.enableEdgeToEdge
   import com.arcgismaps.httpcore.authentication.OAuthUserConfiguration
   import com.arcgismaps.toolkit.authentication.AuthenticatorState
   import com.arcgismaps.toolkit.authentication.DialogAuthenticator
   import com.example.app.screens.MainScreen
   import com.example.app.ui.theme.TutorialTheme
   
   
   class MainActivity : ComponentActivity() {
   
       private val authenticatorState = AuthenticatorState()
   
   
       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)
   
           authenticatorState.oAuthUserConfigurations = listOf(
               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 AuthenticationActivity is defined in the ArcGIS Maps SDK for Kotlin toolkit.

   More info

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

6. The <data> element of AuthenticationActivity 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

   30 collapsed lines
   <?xml version="1.0" encoding="utf-8"?>
   
   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools">
   
       <uses-permission android:name="android.permission.INTERNET" />
   
       <application
           android:allowBackup="true"
           android:dataExtractionRules="@xml/data_extraction_rules"
           android:fullBackupContent="@xml/backup_rules"
           android:icon="@mipmap/ic_launcher"
           android:label="@string/app_name"
           android:roundIcon="@mipmap/ic_launcher_round"
           android:supportsRtl="true"
           android:theme="@style/Theme.Tutorial"
           tools:targetApi="31">
   
           <activity
               android:name=".MainActivity"
               android:exported="true"
               android:label="@string/app_name"
               android:theme="@style/Theme.Tutorial">
               <intent-filter>
                   <action android:name="android.intent.action.MAIN" />
   
                   <category android:name="android.intent.category.LAUNCHER" />
               </intent-filter>
           </activity>
   
           <activity
               android:name="com.arcgismaps.toolkit.authentication.AuthenticationActivity"
               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>
   4 collapsed lines
   
       </application>
   
   </manifest>

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 A map is a collection of layers that are displayed in 2D. It is typically composed of a basemap layer and data layers. Learn more with the topographic basemap layer A basemap layer is the layer in a map or scene that displays basemap data. The data source for a basemap layer is typically a basemap service. Learn more 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