Authentication
ArcGIS supports secure access to location services and private data. It ensures that only valid, authorized users and applications access protected information. To access secure resources, you need to implement an authentication method so your applications can make authenticated requests to services.
An authentication method is the process used obtain an access token. Your app must present an access token whenever it makes an authenticated request to location services. Access tokens define the scope and permissions available to your application. The authentication method you use to get an access token will vary.
There are three kinds of access tokens:
- API key: a permanent token that grants your application access to ready-to-use services and, with an ArcGIS Developer account, private content (currently in beta).
- ArcGIS identity (formerly named user): grants a short-lived token, generated via OAuth 2.0, giving your application permission to access the content and services authorized to an existing ArcGIS user's account.
- Application credentials: grant a short-lived token, generated via OAuth 2.0, authorizing your application to access ready-to-use services.
To make authenticated requests to services, you need to set the token parameter to an access token.
ArcGIS identity
An ArcGIS identity, also known as a named user login, grant a temporary access token giving your application permission to access the content and services authorized to your application user's ArcGIS account. This temporary token is created using OAuth 2.0 protocol and authorizes your application to act on the user's behalf without revealing their secure password to your application. Any service usage is metered and billed to the authenticated user's ArcGIS subscription and, during the authenticated period, your app can access your user's content on their behalf.
Use ArcGIS identity when you want to:
- Ensure users are signed in and authenticated with their own ArcGIS account.
- Meter service usage to your app user's ArcGIS subscription to pay for their private data, content, or service transactions.
- Limit the length of time users can be signed in to your app with a temporary token.
To set up OAuth 2.0 with ArcGIS identity:
For the editor mode, there is a sample OAuth challenge handler that allows you to configure OAuth 2.0 with ArcGIS identity. To load private data in the Scene view:
- Have an ArcGIS account, register an OAuth app, and have a set of Client ID and Redirect URI credentials for your ArcGIS identity to access a private layer. If you don't have an account, sign up for free.
- Open the Map Creator UI and click on the Auth tab.
- In the Add Authentication Configuration section, set a name for the configuration and introduce the Client ID and the Redirect URI for the private content.
- Click on the Add button.
- Click on the tab where you have the private content, Basemap, Elevation, or Layers, and select the configuration name from the Authentication drop-down.
- Save and reload the scene.
When you add a configuration, you can find it under the Authentication Configurations section. When you reload your scene, log in window will be opened in the default web browser window. For adding Basemap, elevation, and layers, see the Layers section.
For play mode, you should have another OAuth challenge handler for your own app. You can attach your own script or OAuth Challenge Handlers Initializer which uses the sample scripts to the game object with the ArcGIS Map Component.
- Click on ArcGIS Map in the Hierarchy window.
- In the Inspector window, click on Add Components button.
- Select OAuth Challenge Handlers Initializer.
When the private data is loaded, the log in window will open in the default web browser window.
For the editor mode, there is a sample OAuth challenge handler that allows you to configure OAuth 2.0 with ArcGIS identity. To load private data in the Scene view:
- Have an ArcGIS account, register an OAuth app, and have a set of Client ID and Redirect URI credentials for your ArcGIS identity to access a private layer. If you don't have an account, sign up for free.
- Go to Unity Editor, and click on the game object with the ArcGIS Map component in the Hierarchy window.
- Open the Authentication section.
- Click on the + icon to add fields for a set of configuration under Authentication Configurations.
- In the newly added fields, set the configuration name, and add the Client ID and the Redirect URI for the private content.
- Under the section you have the private content, select the configuration name from the Authentication drop-down.
- Save and reload the level.
When you reload your scene, the log in window will be opened in the default web browser window. For adding Basemap, elevation, and layers, see the Layers section.
For play mode, you should have another OAuth challenge handler for your own app. You can attach your own script or OAuth Challenge Handlers Initializer which uses the sample scripts to the game object with the ArcGIS Map Component.
- Click on ArcGIS Map in the Hierarchy window.
- In the Inspector window, click on Add Components button.
- Select OAuth Challenge Handlers Initializer.
When the private data is loaded, the log in window will open in the default web browser window.
To use ArcGIS identity, you should have an ArcGIS account, and have a set of Client ID and Redirect URI for your ArcGIS identity to access a private layer. If you don't have an account, sign up for free.
Configure the Client ID and the Redirect URI with ArcGISOAuth for the private content, and register it with the private content URL to the ArcGISAuthentication. If you want to use a new OAuth configuration, clear the registered configurations from the ArcGISAuthentication before you add it.
Use Authentication to set OAuth challenge handler.
For adding private content, see the Layers section.
You can find the sample code to use ArcGIS identity with an ArcGIS Map in the OAuthScene.cs file. The sample script file is in:
Assets/Samples/ArcGIS Maps SDK for Unity/1.1.0/All Samples/Scripts/OAuthScene
The sample script is used in the OAuthAPISample scene in the Assets/ArcGISMapsSDKSamples/URP folder.
You can also find the sample OAuth challenge handler script for desktop and mobile devices in the folder at:
Assets/Samples/ArcGIS Maps SDK for Unity/1.1.0/All Samples/Scripts/Security
API keys
An API key is a long-term access token that you manually create, configure, and scope using the developer dashboard. Using API keys is typically the easiest way to access ArcGIS location services in your applications.
To use API keys, you need to have one of the following ArcGIS accounts:
- ArcGIS Developer account
- ArcGIS Online account
Use API keys when you want to:
- Quickly write applications that consume ready-to-use services.
- Provide access to services without requiring users to sign in with an ArcGIS account.
- Use an access token that doesn't expire.
- Meter service usage to the ArcGIS subscription that owns the API key.
You can set a global API key to use across different scenes in a project.
To set a global API key:
Go to Edit -> Project Settings, in the ArcGIS Maps SDK tab, enter the API key.
To set an API key for a specific scene:
You need an ArcGIS Developer account or ArcGIS Online account and an API key to access ArcGIS services. If you don't have an account, sign up for free.
Open the Map Creator UI in the Unity Editor, and click on the Auth tab.
Introduce the API key in the API Key field.
With the Map Creator UI, the API key is used for all your content. If you want to use different API keys for each data, you should use the C# API.
You need an ArcGIS Developer account or ArcGIS Online account and an API key to access ArcGIS services. If you don't have an account, sign up for free.
Go to Unity Editor, and click on the game object with the ArcGIS Map component in the Hierarchy window.
Open the Authentication section and introduce the API key in the API Key field.
With components, the API key is used for all your content. If you want to use different API keys for each data, you should use the C# API.
To use API keys you need an ArcGIS Developer account or ArcGIS Online account and an API key to access ArcGIS services. If you don't have an account, sign up for free.
You can set API keys for basemap, elevation, and layers. Set the API key string in the constructor.
You can find the sample code to use an API key for all the layers in ArcGIS Map in the SampleAPIMapCreator.cs file. The sample script file is in:
Assets/Samples/ArcGIS Maps SDK for Unity/1.1.0/All Samples/Scripts/APISample
Application credentials
Application credentials grant a short-lived access token, generated via OAuth 2.0, authorizing your application to access ready-to-use services, such as basemap layers, search, and routing.
Use application credentials when you want to:
- Access ready-to-use services with a more secure process and a short-lived token.
- Provide access to services without requiring users to have an ArcGIS account.
Choose an authentication method
The choice of which type of authentication to implement is mostly dependent upon the resources required by your application.
| Scenario | Solution |
|---|---|
| Your app requires access only to ready-to-use services, such as the basemap layer, geocoding, or routing services. | API key |
| Your app allows users to view and edit private data in ArcGIS. | ArcGIS identity |
| Your app is API backend and requires access only to basemaps and geocoding. | Application credentials |