In-App SSO Implementation

Overview

This document describes the two potential approaches for embedding SheerID verification user experience within a native app, including the Single Sign-On (SSO) step, where the verification subject authenticates to their university IdP in order to demonstrate eligibility for the verification program. Because the user needs to exchange their credentials directly with their home IdP, the SSO process must conduct that process in a separate web experience. The options are as follows:

1. Open the IdP page in the system’s default browser, and then redirect back into the app when the user is finished authenticating
2. Spawn a new web view within the native app to conduct the IdP authentication process without leaving the app

Option 1: Login via system default browser

High-level Steps

1. Load SheerID verification program in a webview within native app
2. When the user is prompted to login to IdP, open that URL within default system browser
3. Upon completion of the login process, redirect to a custom app URL that brings the user back into the native app

Step Detail

Load SheerID verification program in a webview within native app

Create a webview and supply the SheerID verification URL. The user will then follow the verification steps within that webview user experience.

Open IdP login URL within system default browser

After submitting the initial verification form data, the user may be prompted to authenticate with their home institution to demonstrate their eligibility. This manifests as a button with default text of “Verify using your school credentials” or similar. Upon clicking this button, the default behavior is to open that URL within the system’s default browser.

Redirect the user back into the native app

This requires the following initial setup steps when developing your native app, and configuring the SheerID verification program accordingly:

• Register a custom scheme for your native app that instructs the user’s system to load that content within the native app (example: myapp://)
• Supply the ssoLoginRedirectUrl configuration directive within SheerID verification program setup so that users are redirected back into the app (example: myapp://sheerid)

If you have followed these setup steps correctly, a successfully authenticated user will be redirected to the custom app scheme. You will then need to ensure that your application handles the custom app URL accordingly. Because the user would have just left the app, it may just be a matter of resuming the webview process that is already in progress. The verification process that is currently displayed within that webview will automatically detect that the authentication attempt has succeeded and the user will be taken to the next step, which could be the “success” step or the next logical step within the configured verification workflow.

Note: If the user is unable to successfully complete the IdP login for whatever reason, they may also directly return to the app and explicitly cancel the in-progress SSO from within the web view to proceed with next steps.

Option 2: Login via web view within native app

Sample Swift code is included below for iOS. A similar approach can be employed for the Android platform as well.

High-level Steps

1. Configure the verification program to allow supplying a ssoLoginRedirectUrl value when loading the verification form
2. Instruct the verification process to redirect back to the verification form upon successful authentication
3. Load SheerID verification program in a SFSafariViewController within native app. Android applications can use Custom Tabs in a similar way

Step Detail (with sample code)

Configure the verification program to allow supplying a ssoLoginRedirectUrl value

Within My SheerID, create a verification program. Under the “Settings” section, find the setting titled “Metadata Tracking”. Enter a value of ssoLoginRedirectUrl and mark this field as Required to ensure we always have a defined redirect URL. Make sure to also enable the Metadata Tracking setting using the toggle switch.

Instruct the verification process to redirect back to the verification form

When building the URL for the embedded SheerID verification form, use the following format:

https://services.sheerid.com/verify//?ssoLoginRedirectUrl=

The value of urlEncodedRedirectUrl should be a URL-encoded value that matches the format shown below, where `` is replaced with your verification program’s ID, and ${requestId} is a variable reference that is interpolated by SheerID’s servers:

https://services.sheerid.com/verify//?verificationId=${requestId}

The resulting value will look like this (query string wrapped onto a new line for readability purposes):

https://services.sheerid.com/verify//
	?ssoLoginRedirectUrl=https://services.sheerid.com/verify//%3FverificationId%3D%24%7BrequestId%7D"

Using this URL to load your verification process will ensure that successfully authenticated users are redirected back into the next appropriate step in the verification flow. In most cases this will be the “success” step after successfully logging in with school credentials.

Load SheerID verification program in a SFSafariViewController within native app

Open the URL constructed in the previous step within a SFSafariViewController, ensuring that the user can complete the entire verification journey without leaving your app. In the event that the user cannot sucessfully authenticate with their institution, they may click on the “back” navigation button, and will be presented an option to proceed with verification by uploading documents.

Complete Swift iOS Sample Code

import SwiftUI
import SafariServices

struct SafariBasedView: View {
    var body: some View {
        Button("Verify your eligibility") {
            // create a SafariViewController targeting the SheerID verification program URL
            let vc = SFSafariViewController(url: URL(string: "https://services.sheerid.com/verify/668c284d8ff1067af3a71aee/?ssoLoginRedirectUrl=https://services.sheerid.com/verify/668c284d8ff1067af3a71aee/%3FverificationId%3D%24%7BrequestId%7D")!)

            // present Safari vc over the root view controller
            UIApplication.shared.firstKeyWindow?.rootViewController?.present(vc, animated: true)
        }
    }
}

extension UIApplication {
    // extension for locating the currently visible window
    var firstKeyWindow: UIWindow? {
        return UIApplication.shared.connectedScenes
            .compactMap { $0 as? UIWindowScene }
            .filter { $0.activationState == .foregroundActive }
            .first?.keyWindow
    }
}

#Preview {
    SafariBasedView()
}