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 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 in the next step. The Client ID is found on the Application item's Overview page, while the Redirect URL is found on the Settings 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 the Xcode project

1. To start the tutorial, complete the Display a map tutorial or download and unzip the solution.

2. Open the .xcodeproj file in Xcode.

Remove API key

An API Key access token is not required for this app because you are implementing user authentication using OAuth 2.0 protocol.

1. Delete the code that sets your API key.

   AppDelegate.swift

   Expand

   Use dark colors for code blocks

   15 15 15 15 15 15 15 15 15 15 15 15 15 15 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

   Remove 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
   33
   import UIKit
   
   import ArcGIS
   
   
   @UIApplicationMain
   class AppDelegate: UIResponder, UIApplicationDelegate {
       var window: UIWindow?
   
       func application(_ application: UIApplication,
                        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
   
           AGSArcGISRuntimeEnvironment.apiKey = "YOUR_ACCESS_TOKEN"
   
           return true
       }
   
   }

Set the app settings

Create a new Swift file and define constants you'll need in the app.

1. Add a new Swift file to your Xcode project named AppConfiguration. You will use this file to hold configuration constants required by your app.

   More info

   • In Xcode's app menu, select File > New > File.
   • Select Swift File from the Source sub-menu.
   • Name the file AppConfiguration and ensure your app's target is checked.
   • Click create.

2. Add the following to AppConfiguration.swift. Change "YOUR-APP-CLIENT-ID" to the Client ID obtained in the Create OAuth credentials for user authentication step. Change "YOUR-APP-REDIRECT-URL" to match your Redirect URL entry above.

   AppConfiguration.swift

   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
   extension String {
       static let clientID = "YOUR-APP-CLIENT-ID"
       static var redirectURL = "YOUR-APP-REDIRECT-URL"
       static let keychainIdentifier = "\(Bundle.main.bundleIdentifier!).keychainIdentifier"
   }
   
   extension URL {
       static let trafficLayerURL = URL(string: "https://traffic.arcgis.com/arcgis/rest/services/World/Traffic/MapServer")!
   }

Add layer to map

Add an operational layer to the map and test run the app.

1. Open ViewController.swift and update the existing setupMap() method to add the World Traffic layer to the map.

   More info

   The World Traffic layer is a premium service on ArcGIS Online that requires authentication for access.

   ViewController.swift

   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
           let trafficLayer = AGSArcGISMapImageLayer(url: .trafficLayerURL)
           map.operationalLayers.add(trafficLayer)
   

   Expand

2. Press <Command+R> to run the app.

Only the basemap displays in the map. The traffic layer will not load until you use the AGSAuthenticationManager to log in with an authorized account.

Integrate OAuth credentials into your app

Add OAuth components to your app, including adding the Redirect URL to the app's plist file, and setting up AGSAuthenticationManager.

1. Configure a redirect URL scheme for your app. Right-click on info.plist file in the Project Navigator and then select Open As > / Source Code. Edit the file just after the opening top-level <dict> tag and add the following XML:

   More info

   Be sure to use your exact bundle identifier for your app.

   Use the scheme part of the Redirect URL you configured in the application definition, but without the path (everything before the ://). This is how OAuth 2.0 in iOS is able to return information about the authentication process back to your app. Note these strings must match exactly.

   Info.plist

   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
   	<key>CFBundleURLTypes</key>
   	<array>
   		<dict>
   			<key>CFBundleTypeRole</key>
   			<string>Editor</string>
   			<key>CFBundleURLName</key>
   			<string>com.esri.access-services-with-oauth</string>
   			<key>CFBundleURLSchemes</key>
   			<array>
   				<string>my-app</string>
   			</array>
   		</dict>
   	</array>
   

   Expand

2. Open AppDelegate.swift to setup the AGSAuthenticationManager in your AppDelegate. Import the ArcGIS library.

   AppDelegate.swift

   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
   import UIKit
   
   import ArcGIS
   

   Expand

3. Add a new method to setup the authentication manager in AppDelegate.swift. This code creates a configuration with the parameters you assigned to your app in AppConfiguration and then assigns that configuration to the AGSAuthenticationManager. The credentials are also saved in the device's keychain.

   More info

   To construct the required redirectURL, combine the urlScheme and urlAuthPath from your AppConfiguration separated with ://.

   AppDelegate.swift

   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
   // MARK: - OAuth
   extension AppDelegate {
       private func setupOAuthManager() {
           // Initialize OAuth configuration with Client ID and Redirect URL.
           let config = AGSOAuthConfiguration(portalURL: nil,
                                              clientID: .clientID,
                                              redirectURL: .redirectURL)
           // Add OAuth configuration to authentication manager.
           AGSAuthenticationManager.shared()
               .oAuthConfigurations
               .add(config)
           // Enable auto-sync to keychain on the auth manager's credential cache.
           AGSAuthenticationManager.shared()
               .credentialCache
               .enableAutoSyncToKeychain(withIdentifier: .keychainIdentifier,
                                         accessGroup: nil,
                                         acrossDevices: false)
       }
   }

4. Add a call to setupOAuthManager() from the application launch.

   AppDelegate.swift

   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
       func application(_ application: UIApplication,
                        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
   
           setupOAuthManager()
   
           return true
       }
   

   Expand

5. Press Command + R to run the app.

   More info

   If you are using the Xcode simulator your system must meet these minimum requirements: macOS Big Sur 11.3, Xcode 13, iOS 13. If you are using a physical device, then refer to the system requirements.

What's next?

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

• Display a web map