Ping SDKs

Configure iOS apps for OIDC login

This section describes how to configure your Ping 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.

    If you do not want to implement Universal Links, you can instead use a custom scheme for your redirect URIs.

    • 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 Capability, type Associated Domains, and then double click the result to add the capability.

    3. In Domains, click the Add () button, and enter applinks:, followed by the hostname that will be used in your redirect URIs.

      Adding an associated domain in Xcode

      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
      {
  "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.

      For learn more information about Universal Links and associating domains, refer to the following in the Apple Developer documentation:

    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

    3. Add the custom URL scheme to the Redirection URIs property of your OAuth 2.0 client:

      OAuth 2.0 Redirection URI

  2. Update your application to call the validateBrowserLogin() function:

    1. In your AppDelegate.swift file, call the validateBrowserLogin() function:

      AppDelegate.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
      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
      class SceneDelegate: UIResponder, UIWindowSceneDelegate {

  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    if let url = URLContexts.first?.url {
      Browser.validateBrowserLogin(url)
    }
  }
}

  3. To enable centralized login, add code similar to the following to your app:

    //  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 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 SDK for iOS.

    .ephemeralAuthSession

    Opens a web authentication session browser, but enables the 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. This means that an ephemeralAuthSession is not suitable when you require single sign-on (SSO) between your iOS apps.

    Use this browser type 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 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.