--- title: Configure iOS apps for OIDC login description: This section describes how to configure your Ping (ForgeRock) SDK for iOS application to use centralized login: component: sdks version: latest page_id: sdks:oidc:sdkconfiguration/oidc-login/ios-centralized-login canonical_url: https://docs.pingidentity.com/sdks/latest/oidc/sdkconfiguration/oidc-login/ios-centralized-login.html revdate: Mon, 30 Sep 2024 13:44:17 +0100 keywords: ["OAuth 2.0", "OpenID Connect", "Setup & Configuration", "Source Code", "Integration", "SDK"] --- # Configure iOS apps for OIDC login This section describes how to configure your Ping (ForgeRock) SDK for iOS application to use centralized login: 1. Associate your application with the scheme your redirect URIs use. To ensure that only your app is able to obtain authorization tokens during centralized login we recommend you configure it to use [Universal Links](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app?language=objc). If you do not want to implement Universal Links, you can instead use a custom scheme for your redirect URIs. * Apple Universal Links * Custom scheme Complete the following steps to configure Universal Links: 1. In Xcode, in the Project Navigator, double-click your application to open the Project pane. 2. On the Signing & Capabilities tab, click [icon: plus, set=fa]Capability, type `Associated Domains`, and then double click the result to add the capability. 3. In Domains, click the Add ([icon: plus, set=fa]) button, and enter `applinks:`, followed by the hostname that will be used in your redirect URIs. ![Adding an associated domain in Xcode](../../../_images/ios-xcode-applink-en.png) The host value must match the domain where you upload the `apple-app-site-association` file. 4. Create or update an `apple-app-site-association` file that associates your app with the domain. You must host the file in a `.well-known` folder on the same host that you entered in the intent filter earlier. The file will resemble the following: https\://ios.example.com/.well-known/apple-app-site-association ```json { "applinks": { "details": [ { "appIDs": [ "XXXXXXXXXX.com.example.AppName" ], "components": [ { "/": "/oauth2redirect", "comment": "Associate my app with the OAuth 2.0 redirect URI." } ] } ] } } ``` 5. Upload the completed file to the domain that matches the host value you configured in the earlier step. For information on uploading an `apple-app-site-association` file to an Advanced PingOne Advanced Identity Cloud instance, refer to [Upload an iOS apple-app-site-association file](https://docs.pingidentity.com/pingoneaic/latest/end-user/upload-ios-apple-app-site-association.html). For learn more information about Universal Links and associating domains, refer to the following in the Apple Developer documentation: * [Supporting universal links in your app](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app?language=objc) * [Supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains?language=objc) 6. Add the Universal Link to the Redirection URIs property of your OAuth 2.0 client. For example, `https://ios.example.com/oauth2redirect` Configure a custom URL type, for example `frauth`, so that users are redirected to your application: 1. In Xcode, in the Project Navigator, double-click your application to open the Project pane. 2. On the Info tab, in the URL Types panel, configure your custom URL scheme: ![Custom URL Scheme](../../../_images/custom_url_scheme.png) 3. Add the custom URL scheme to the Redirection URIs property of your OAuth 2.0 client: ![OAuth 2.0 Redirection URI](../../../_images/custom_url_scheme_client.png) 2. Update your application to call the `validateBrowserLogin()` function: 1. In your `AppDelegate.swift` file, call the `validateBrowserLogin()` function: `AppDelegate.swift` ```swift class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool { // Parse and validate URL, extract authorization code, and continue the flow: Browser.validateBrowserLogin(url) } } ``` 2. If you are using Universal Links, also add code similar to the following to set the URL: `AppDelegate.swift` ```swift func application( _ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool { // Get URL components from the incoming user activity. guard userActivity.activityType == NSUserActivityTypeBrowsingWeb, let incomingURL = userActivity.webpageURL else { return false } Browser.validateBrowserLogin(url) } ) ``` 3. If your application is using `SceneDelegate`, in your `SceneDelegate.swift` file call the `validateBrowserLogin()` function: `SceneDelegate.swift` ```swift class SceneDelegate: UIResponder, UIWindowSceneDelegate { func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { if let url = URLContexts.first?.url { Browser.validateBrowserLogin(url) } } } ``` 3. To enable centralized login, add code similar to the following to your app: ```swift // BrowserBuilder let browserBuilder = FRUser.browser() browserBuilder.set(presentingViewController: self) browserBuilder.set(browserType: .authSession) browserBuilder.setCustomParam(key: "custom_key", value: "custom_val") // Browser let browser = browserBuilder.build() // Login browser.login{ (user, error) in if let error = error { // Handle error } else if let user = user { // Handle authenticated status } } ``` You can specify what type of browser the client iOS device opens to handle centralized login. Each browser has slightly different characteristics, which make them suitable to different scenarios, as outlined in this table: | Browser type | Characteristics | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `.authSession` | Opens a [web authentication session](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) browser.Designed specifically for authentication sessions, however it prompts the user before opening the browser with a modal that asks them to confirm the domain is allowed to authenticate them.This is the default option in the Ping (ForgeRock) SDK for iOS. | | `.ephemeralAuthSession` | Opens a [web authentication session](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) browser, but enables the [`prefersEphemeralWebBrowserSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession/prefersephemeralwebbrowsersession) parameter.This browser type *does not* prompt the user before opening the browser with a modal.The difference between this and `.authSession` is that the browser does not include any existing data such as cookies in the request, and also discards any data obtained during the browser session, including any session tokens.When is `ephemeralAuthSession` suitable:- [icon: times, set=fa]`ephemeralAuthSession` is *not* suitable when you require single sign-on (SSO) between your iOS apps, as the browser will not maintain session tokens. - [icon: times, set=fa]`ephemeralAuthSession` is *not* suitable when you require a session token to log a user out of the server, for example for logging out of PingOne, as the browser will not maintain session tokens. - [icon: check, set=fa]Use `ephemeralAuthSession` when you do not want the user's existing sessions to affect the authentication. | | `.nativeBrowserApp` | Opens the installed browser that is marked as the default by the user. Often Safari.The browser opens without any interaction from the user. However, the browser does display a modal when returning to your application. | | `.sfViewController` | Opens a [Safari view controller](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) browser.Your client app is ***not*** able to interact with the pages in the `sfViewController` or access the data or browsing history.The view controller opens within your app without any interaction from the user. As the user does not leave your app, the view controller does not need to display a warning modal when authentication is complete and control returns to your application. |