Ping SDKs

Set up centralized login in iOS apps

Applies to:

  • Ping SDK for Android

  • Ping SDK for iOS

  • Ping SDK for JavaScript

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

    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 by using the browserType parameter.

    Each browser has slightly different characteristics, which make them suitable to different scenarios, as outlined in this table:

    browserType 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.