oidc-hosted-page-ios

This expert AI assistant guide walks you through integrating "Sign in with SSO" functionality into an existing iOS application using SSOJet as an OIDC identity provider via AppAuth for iOS.

1. Prerequisites

• An existing iOS 15+ application (Swift 5.7+) with a login screen.
• Xcode 14+ installed.
• An active SSOJet account.
• SSO Connection Setup Guide
• Required library: openid/AppAuth-iOS.

2. Implementation Steps

Step 1: Create Application in SSOJet

1. Log in to the SSOJet Dashboard.
2. Navigate to Applications.
3. Create a new application (e.g., "MyiOSApp", type Native / Mobile).
4. Configure the callback URI using a custom scheme (e.g., com.example.myapp://auth/callback).
5. Retrieve Client ID.
6. Copy the Issuer URL from the Advanced > Endpoints section.

Note: For native/mobile apps, use Authorization Code with PKCE (no Client Secret on the device).

Step 2: Modify the Existing iOS Project

Substep 2.1: Add Dependencies

Add AppAuth via Swift Package Manager:

1. In Xcode, go to File > Add Package Dependencies.
2. Enter: https://github.com/openid/AppAuth-iOS.git.
3. Select the latest stable version and add to your target.

Or via CocoaPods:

# Podfile
pod 'AppAuth'

pod install

Substep 2.2: Configure URL Scheme

Add a custom URL scheme in your Info.plist:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>com.example.myapp</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.example.myapp</string>
    </dict>
</array>

Substep 2.3: Configure OIDC

Create an auth configuration helper (e.g., AuthConfig.swift):

// AuthConfig.swift
import Foundation

struct AuthConfig {
    static let issuerURL = URL(string: "https://auth.ssojet.com")!
    static let clientID = "your_client_id"
    static let redirectURI = URL(string: "com.example.myapp://auth/callback")!
    static let scopes = ["openid", "profile", "email"]
}

Substep 2.4: Create Auth Manager

Create a centralised auth manager (e.g., AuthManager.swift):

// AuthManager.swift
import UIKit
import AppAuth

class AuthManager: NSObject {
    static let shared = AuthManager()
    var currentAuthorizationFlow: OIDExternalUserAgentSession?
    var authState: OIDAuthState?

    func login(from viewController: UIViewController, loginHint: String?, completion: @escaping (Result<OIDAuthState, Error>) -> Void) {
        // Discover OIDC configuration
        OIDAuthorizationService.discoverConfiguration(forIssuer: AuthConfig.issuerURL) { config, error in
            guard let config = config else {
                completion(.failure(error ?? NSError(domain: "OIDC", code: -1, userInfo: [NSLocalizedDescriptionKey: "Discovery failed"])))
                return
            }

            // Build authorization request
            var additionalParams: [String: String] = [:]
            if let hint = loginHint, !hint.isEmpty {
                additionalParams["login_hint"] = hint
            }

            let request = OIDAuthorizationRequest(
                configuration: config,
                clientId: AuthConfig.clientID,
                scopes: AuthConfig.scopes,
                redirectURL: AuthConfig.redirectURI,
                responseType: OIDResponseTypeCode,
                additionalParameters: additionalParams
            )

            // Launch auth flow
            self.currentAuthorizationFlow = OIDAuthState.authState(
                byPresenting: request,
                presenting: viewController
            ) { authState, error in
                if let authState = authState {
                    self.authState = authState
                    print("Authenticated! Access Token: \(authState.lastTokenResponse?.accessToken ?? "nil")")
                    completion(.success(authState))
                } else {
                    print("OIDC Error: \(error?.localizedDescription ?? "Unknown error")")
                    completion(.failure(error ?? NSError(domain: "OIDC", code: -1)))
                }
            }
        }
    }

    func logout() {
        authState = nil
    }
}

Substep 2.5: Handle Redirect in AppDelegate / SceneDelegate

// AppDelegate.swift (or SceneDelegate.swift)
import AppAuth

// In AppDelegate:
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    if let flow = AuthManager.shared.currentAuthorizationFlow,
       flow.resumeExternalUserAgentFlow(with: url) {
        AuthManager.shared.currentAuthorizationFlow = nil
        return true
    }
    return false
}

// If using SceneDelegate:
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    if let flow = AuthManager.shared.currentAuthorizationFlow,
       flow.resumeExternalUserAgentFlow(with: url) {
        AuthManager.shared.currentAuthorizationFlow = nil
    }
}

Substep 2.6: Update Login View Controller

// LoginViewController.swift
import UIKit

class LoginViewController: UIViewController {
    private let emailTextField = UITextField()
    private let passwordTextField = UITextField()
    private let signInButton = UIButton(type: .system)
    private let ssoToggleButton = UIButton(type: .system)
    private var isSSO = false

    override func viewDidLoad() {
        super.viewDidLoad()
        setupUI()
    }

    private func setupUI() {
        view.backgroundColor = .systemBackground
        title = "Sign In"

        emailTextField.placeholder = "Email"
        emailTextField.keyboardType = .emailAddress
        emailTextField.borderStyle = .roundedRect

        passwordTextField.placeholder = "Password"
        passwordTextField.isSecureTextEntry = true
        passwordTextField.borderStyle = .roundedRect

        signInButton.setTitle("Sign In", for: .normal)
        signInButton.addTarget(self, action: #selector(handleSignIn), for: .touchUpInside)

        ssoToggleButton.setTitle("Sign in with SSO", for: .normal)
        ssoToggleButton.addTarget(self, action: #selector(toggleSSO), for: .touchUpInside)

        let stack = UIStackView(arrangedSubviews: [emailTextField, passwordTextField, signInButton, ssoToggleButton])
        stack.axis = .vertical
        stack.spacing = 16
        stack.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(stack)

        NSLayoutConstraint.activate([
            stack.centerYAnchor.constraint(equalTo: view.centerYAnchor),
            stack.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 24),
            stack.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -24),
        ])
    }

    @objc private func toggleSSO() {
        isSSO.toggle()
        passwordTextField.isHidden = isSSO
        signInButton.setTitle(isSSO ? "Continue with SSO" : "Sign In", for: .normal)
        ssoToggleButton.setTitle(isSSO ? "Back to Password Login" : "Sign in with SSO", for: .normal)
    }

    @objc private func handleSignIn() {
        let email = emailTextField.text ?? ""

        if isSSO {
            AuthManager.shared.login(from: self, loginHint: email) { result in
                DispatchQueue.main.async {
                    switch result {
                    case .success:
                        let dashboard = DashboardViewController()
                        self.navigationController?.pushViewController(dashboard, animated: true)
                    case .failure(let error):
                        let alert = UIAlertController(title: "Error", message: error.localizedDescription, preferredStyle: .alert)
                        alert.addAction(UIAlertAction(title: "OK", style: .default))
                        self.present(alert, animated: true)
                    }
                }
            }
        } else {
            print("Processing traditional login...")
        }
    }
}

Step 3: Test the Modified Connection

1. Run on a simulator or device.
2. Verify the login screen shows Email + Password by default.
3. Tap "Sign in with SSO" and ensure the password field hides.
4. Enter a test email and tap "Continue with SSO".
5. A browser/ASWebAuthenticationSession opens to SSOJet.
6. Authenticate and verify you are redirected back to the app.

3. Additional Considerations

• Security: PKCE is handled automatically by AppAuth. Never embed Client Secrets in mobile apps.
• Token Storage: Use the iOS Keychain to store tokens securely.
• SwiftUI: For SwiftUI apps, wrap the OIDAuthState.authState(byPresenting:) call in a coordinator or use ASWebAuthenticationSession directly.

4. Support

• Contact SSOJet support: Reach out if you have integration questions.
• Library Documentation: Refer to the AppAuth for iOS documentation.