In-App SSO Implementation
In this guide, we’ll go through the steps to embed SheerID verification 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.
What You’ll Build
In this tutorial you’ll integrate SheerID verification into a native mobile app so users can complete the SheerID form and the school Single Sign-On (IdP) step without leaving your app — using the system browser or an in-app web view — and return to the right step in your flow when they finish.
Prerequisites
- A published verification program and its
programId(create one in MySheerID). - The
ssoLoginRedirectUrlvalue configured under your program’s Metadata Tracking settings (used by both options below).
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:
- Open the IdP page in the system’s default browser, and then redirect back into the app when the user is finished authenticating
- 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
- Load SheerID verification program in a webview within native app
- When the user is prompted to login to IdP, open that URL within default system browser
- 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
ssoLoginRedirectUrlconfiguration 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
- Configure the verification program to allow supplying a
ssoLoginRedirectUrlvalue when loading the verification form - Instruct the verification process to redirect back to the verification form upon successful authentication
- Load SheerID verification program in a
SFSafariViewControllerwithin 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/YOUR_PROGRAM_ID/?ssoLoginRedirectUrl=https://services.sheerid.com/verify/YOUR_PROGRAM_ID/%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()
}
Next Steps
- Authentication — authenticate verification creation.
- Secure Verification Creation — pre-generate the verification, then redirect to the form.
- Webhooks — get notified of the outcome.