Single Sign On (SSO) with Mobile SDKs

Descope supports SSO as one of the authentication methods for your end-users. When using SSO, the SSO configuration can be different for each tenant. Please refer to the article in the manage section for the configuration of SSO for each tenant.

Client SDK

Install SDK

// 1. Within XCode, go to File > Add Packages
// 2. Search for the URL of the git repo: https://github.com/descope/descope-swift
// 3. Configure your desired dependency rule
// 4. Click Add Package

Import and initialize SDK

import DescopeKit
import AuthenticationServices
 
do {
    Descope.setup(projectId: "__ProjectID__") { config in
      // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
      config.baseURL = "https://auth.app.example.com"
    }
    print("Successfully initialized Descope")
} catch {
    print("Failed to initialize Descope")
    print(error)
}

Start SSO

To initiate the SSO process, call the SSO initiation function after the user clicks the login button. This function automatically opens the SSO Identity Provider's login screen in a browser webview.

// Args:
//   emailOrTenantName: ID of the tenant that the user is authenticating to. The tenant ID is assigned to tenant at the time of creation.
let emailOrTenantName = "email@company.com"
//   redirect_url: URL to return to after successful authentication with the SSO identity provider. You need to implement this page to access the token and finish oauth process (token exchange). The token arrives as a query parameter named 'code'.
let redirectURL = "exampleauthschema://auth.company.com/handle-sso"
 
guard let session = Descope.sessionManager.session else { return }
var signInOptions: [SignInOptions] = [
    .customClaims(["name": "{{user.name}}"]),
    .mfa(refreshJwt: session.refreshJwt),
    .stepup(refreshJwt: session.refreshJwt)
]
 
do {
  let authURL = try await Descope.sso.start(emailOrTenantName: emailOrTenantName, redirectURL: redirectURL, options: signInOptions)
  guard let authURL = URL(string: authURL) else { return }
  print("Successfully initiated SSO Authentication")
} catch {
  print("Failed to initiate SSO Authentication")
  print(error)
}

SSO Exchange Code

After successful authentication with your IdP the user is redirected to the redirect_url that you provide in the sso start function above. Your application should extract the code from the redirect_url and perform token exchange as shown below.

// Args:
//   authURL: the authURL generated from the Start SSO
let authURL = "xxxxx"
 
do {
  let session = ASWebAuthenticationSession(
    url: authURL,
    callbackURLScheme: "exampleauthschema") { callbackURL, error in
      guard let url = callbackURL else {return}
      let component = URLComponents(url: url, resolvingAgainstBaseURL: false)
      guard let code = component?.queryItems?.first(where: {$0.name == "code"})?.value else { return }
      print(code)
 
      // Exchange code for session
      Task {
        do {
          let descopeSession = try await Descope.sso.exchange(code: code)
          print("Successfully Completed SSO Authentication")
          print(descopeSession as Any)
        } catch {
          print("Failed to Complete SSO Authentication")
          print(error)
      }
    }
  }
  session.presentationContextProvider = self
  session.prefersEphemeralWebBrowserSession = true
  session.start()
} catch {
  print("Failed to Complete SSO Authentication")
  print(error)
}

Session Validation

The final step of completing the authentication with Descope is to validate the user session. Descope provides rich session management capabilities, including configurable session timeouts and logout functions. You can find the details and sample code for client session validation here.

Checkpoint

Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Need help?

Was this helpful?