Access services with OAuth credentials

Before starting this tutorial:

1. You need an ArcGIS Location Platform or ArcGIS Online account.

2. Your system meets the system requirements.

Create a new OAuth credential to access the secured resources used in this tutorial.

1. Complete the Create OAuth credentials for user authentication tutorial.

2. Copy and paste the ClientID and RedirectURL into a safe location. They will be used in a later step.

All users that access this application need account privileges Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS. Learn more to access the basemap styles service The ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service. Learn more .

Option 1: Develop the code

Create a new app

To get started, use Xcode to create an iOS app and configure it to reference the API.

1. Open Xcode. In the menu bar, click File > New > Project.

   • In the Choose a template for your new project: window, set the following properties:
     • Multiplatform iOS
     • Application App
   • Click Next.
   • In the Choose options for your new project: window, set the following properties:
     • Product Name: <your app name>
     • Organization Identifier: <your organization>
     • Interface: SwiftUI
     • Language: Swift
   • Uncheck all other options.
   • Click Next.
   • Choose a location to store your project. Click Create.

2. In the Project Navigator, click <your app name>App. In the Editor, right click on the struct name, <your app name>App. Select Refactor > Rename… to rename the struct to MainApp. Click the Rename button in the top right to confirm the new name. This will rename the struct and file in all affected areas.

3. Add a reference to the API using Swift Package Manager.

4. In the MainApp.swift file, some errors may appear after importing ArcGIS. Resolve the errors by distinguishing the Scene protocol from Scene. To do so, add the SwiftUI prefix to Scene.

   MainApp.swift

       var body: some SwiftUI.Scene {
   
           WindowGroup {
               ContentView()
   
           }
       }

Add a protected layer to map

Add the World Traffic layer to the map.

1. In the Project Navigator, click ContentView.swift.

2. In the Editor, add an import statement to reference the API.

   ContentView.swift

   1
   import SwiftUI
   2
   
   3
   import ArcGIS

3. Add a Map with the @State property wrapper with a default value. Create a Map with an arcGISTopographic basemap style and an inital viewpoint and return it.

   ContentView.swift

   1
   struct ContentView: View {
   2
   
   3
       @State private var map = {
   4
           let map = Map(basemapStyle: .arcGISTopographic)
   5
           map.initialViewpoint = Viewpoint(latitude: 34.02700, longitude: -118.80500, scale: 72_000)
   6
   
   7
           return map
   8
       }()

4. Add a secured traffic layer to the map’s operational layers collection.

   More info

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

   ContentView.swift

   1
       @State private var map = {
   2
           let map = Map(basemapStyle: .arcGISTopographic)
   3
           map.initialViewpoint = Viewpoint(latitude: 34.02700, longitude: -118.80500, scale: 72_000)
   4
   
   5
           let trafficLayerURL = URL(string: "http://www.arcgis.com/home/item.html?id=ff11eb5b930b4fabba15c47feb130de4")!
   6
           let trafficLayer = ArcGISMapImageLayer(url: trafficLayerURL)
   7
           map.addOperationalLayer(trafficLayer)
   8
   
   9
           return map
   10
       }()

5. Replace the default code in the body to display the map. Create a MapView using the previously created map.

   ContentView.swift

   1
       var body: some View {
   2
   
   3
           MapView(map: map)
   4
   
   5
       }

6. Open the MainApp.swift file. Add the .ignoreSafeArea modifier to the ContentView. This modifier ensures that the map view is displayed beyond the safe area to all edges.

   MainApp.swift

   1
       var body: some SwiftUI.Scene {
   2
   
   3
           WindowGroup {
   4
               ContentView()
   5
   
   6
                   .ignoresSafeArea()
   7
   
   8
           }
   9
       }

Integrate OAuth credentials into your app

Use the ArcGIS Maps SDK for Swift Toolkit component to create an Authenticator object that handles authentication every time a secured ArcGIS resource is accessed.

1. The Toolkit is required to access the Authenticator component. Follow the installation instructions to add Toolkit to the MainApp.swift file.

   MainApp.swift

   1
   import SwiftUI
   2
   import ArcGIS
   3
   
   4
   import ArcGISToolkit

2. Create an Authenticator object with the Observed Object property wrapper.

   MainApp.swift

   1
   struct MainApp: App {
   2
   
   3
       // Setup an `Authenticator` with OAuth configuration.
   4
       @ObservedObject var authenticator = Authenticator(
   5
           oAuthUserConfigurations: [
   6
   
   7
           ]
   8
       )

3. Initialize the Authenticator with an OAuthConfiguration object. Use your ClientID and RedirectURL credentials that you created in the Set up authentication step.

   More info

   • Portal is the URL of the portal to authenticate with. For the purpose of this tutorial, the URL is https://www.arcgis.com.
   • ClientID unique identifier associated with an application registered with the portal that assists with client/server OAuth authentication.
   • RedirectURL is the URL that the OAuth login page will redirect to when authentication completes.
   MainApp.swift

   1
       // Setup an `Authenticator` with OAuth configuration.
   2
       @ObservedObject var authenticator = Authenticator(
   3
           oAuthUserConfigurations: [
   4
   
   5
               OAuthUserConfiguration(
   6
                   // Enter OAuth credentials for user authentication.
   7
                   portalURL: URL(string: "https://www.arcgis.com")!,
   8
                   clientID: "<#YOUR-CLIENT-ID#>",
   9
                   redirectURL: URL(string: "<#YOUR-REDIRECT-URL#>")!
   10
               )
   11
   
   12
           ]
   13
       )

4. Create an initializer function and assign the authenticator to the ArcGISAuthenticationChallengeHandler. This points the challenge to the authenticator which will handle the request.

   MainApp.swift

   1
   struct MainApp: App {
   2
   
   3
       // Setup an `Authenticator` with OAuth configuration.
   4
       @ObservedObject var authenticator = Authenticator(
   5
           oAuthUserConfigurations: [
   6
   
   7
               OAuthUserConfiguration(
   8
                   // Enter OAuth credentials for user authentication.
   9
                   portalURL: URL(string: "https://www.arcgis.com")!,
   10
                   clientID: "<#YOUR-CLIENT-ID#>",
   11
                   redirectURL: URL(string: "<#YOUR-REDIRECT-URL#>")!
   12
               )
   13
   
   14
           ]
   15
       )
   16
   
   17
       init() {
   18
           ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler = authenticator
   19
       }

5. Lastly, display the OAuth interface. Add the authenticator view modifier, passing in the authenticator object.

   MainApp.swift

   1
       var body: some SwiftUI.Scene {
   2
   
   3
           WindowGroup {
   4
               ContentView()
   5
   
   6
                   .authenticator(authenticator)
   7
   
   8
                   .ignoresSafeArea()
   9
   
   10
           }
   11
       }

6. Press Command+R to run the app.

Upon app launch, you will be prompted to log in with your ArcGIS Location Platform or ArcGIS Online credentials. Once you authenticate successfully, the basemap and traffic layer will appear in the map.

Manage data persistence

In real-world applications, you can create and persist a credential store in the keychain so that the user does not have to sign in again when the app is re-launched.

1. Create an asynchronous function called setupPersistentCredentialStorage that sets up new credential stores that will be persisted to the keychain. Use the authenticationManager.setupPersistentCredentialStorage method to create the credential store and set the keychain access to whenUnlocked. This will allow the item to be accessible only when device is unlocked.

   MainApp.swift

   1
       init() {
   2
           ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler = authenticator
   3
       }
   4
   
   5
       private func setupPersistentCredentialStorage() async {
   6
           Task {
   7
               try await ArcGISEnvironment.authenticationManager.setupPersistentCredentialStorage(access: .whenUnlocked)
   8
           }
   9
       }

2. Set up the credential stores upon app launch. Add a task function to ContentView. In the closure, call the setupPersistentCredentialStorage function.

   MainApp.swift

   1
       var body: some SwiftUI.Scene {
   2
   
   3
           WindowGroup {
   4
               ContentView()
   5
   
   6
                   .authenticator(authenticator)
   7
   
   8
                   .ignoresSafeArea()
   9
   
   10
                   .task {
   11
                       await setupPersistentCredentialStorage()
   12
                   }
   13
   
   14
           }
   15
       }

3. Press Command + R to run the app.

   More info

   If you are using the Xcode simulator your system must meet these minimum requirements: macOS 14 (Sonoma), Xcode 16, iOS 18. If you are using a physical device, then refer to the system requirements.

Upon app launch, you will not be prompted to log in again.

Option 2: Download the solution

1. Click the Download solution link under Solution and unzip the file to a location on your machine.

2. Open the .xcodeproj file in Xcode.

Since the downloaded solution does not contain authentication credentials, you must add the developer credentials that you created in the Set up authentication section.

Set developer credentials in the solution

1. In the Project Navigator, click MainApp.swift.

2. Enter your clientID and redirectURL values that you created earlier.

   MainApp.swift

   24 collapsed lines
   1
   // Copyright 2025 Esri
   2
   //
   3
   // Licensed under the Apache License, Version 2.0 (the "License");
   4
   // you may not use this file except in compliance with the License.
   5
   // You may obtain a copy of the License at
   6
   //
   7
   //   https://www.apache.org/licenses/LICENSE-2.0
   8
   //
   9
   // Unless required by applicable law or agreed to in writing, software
   10
   // distributed under the License is distributed on an "AS IS" BASIS,
   11
   // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   12
   // See the License for the specific language governing permissions and
   13
   // limitations under the License.
   14
   
   15
   
   16
   import SwiftUI
   17
   import ArcGIS
   18
   
   19
   import ArcGISToolkit
   20
   
   21
   @main
   22
   
   23
   struct MainApp: App {
   24
   
   25
       // Setup an `Authenticator` with OAuth configuration.
   26
       @ObservedObject var authenticator = Authenticator(
   27
           oAuthUserConfigurations: [
   28
   
   29
               OAuthUserConfiguration(
   30
                   // Enter OAuth credentials for user authentication.
   31
                   portalURL: URL(string: "https://www.arcgis.com")!,
   32
                   clientID: "<#YOUR-CLIENT-ID#>",
   33
                   redirectURL: URL(string: "<#YOUR-REDIRECT-URL#>")!
   34
               )
   35
   
   36
           ]
   37
       )
   28 collapsed lines
   38
   
   39
       init() {
   40
           ArcGISEnvironment.authenticationManager.arcGISAuthenticationChallengeHandler = authenticator
   41
       }
   42
   
   43
       private func setupPersistentCredentialStorage() async {
   44
           Task {
   45
               try await ArcGISEnvironment.authenticationManager.setupPersistentCredentialStorage(access: .whenUnlocked)
   46
           }
   47
       }
   48
   
   49
       var body: some SwiftUI.Scene {
   50
   
   51
           WindowGroup {
   52
               ContentView()
   53
   
   54
                   .authenticator(authenticator)
   55
   
   56
                   .ignoresSafeArea()
   57
   
   58
                   .task {
   59
                       await setupPersistentCredentialStorage()
   60
                   }
   61
   
   62
           }
   63
       }
   64
   
   65
   }

Best Practice: The OAuth credentials are stored directly in the code as a convenience for this tutorial. Do not store credentials directly in source code in a production environment.

Run the solution

Press Command + R to run the app.

Upon app launch, you will be prompted to log in with your ArcGIS Location Platform or ArcGIS Online credentials. Once you authenticate successfully, the basemap and traffic layer will appear in the map.