App-to-app flow
Some identity providers authenticate the end-user in their own mobile app rather than on a web page. This is known as an app-to-app flow.
How it works
The SDK manages OIDC authentication through the following steps:
- Your app requests the identity provider's app through the
acrValuesproperty of yourOIDCConfiguration. For details, see the Configuration reference section on the iOS Set up the SDK page. - Your app calls
login(appLinkHandler:), and the SDK starts the OIDC flow. - The SDK shows a waiting screen and follows the redirects of the Signicat service itself. When a redirect leads to the identity provider, iOS opens the identity provider's app and authenticates the end-user.
- The identity provider's app opens a universal link to your app. Your app passes the link to
handle(url:). - The SDK passes the link to your
appLinkHandler, which validates it and returns the URL that continues the flow. - The SDK follows the redirects from that URL to your redirect URI, closes the waiting screen and returns a session.
Your app must handle steps 4 and 5. The identity provider's return link arrives on your domain and is received by your app, so you must pass it to the SDK and validate it in your appLinkHandler.
What your app needs
To support an app-to-app flow, your app needs to meet the requirements described in the following three sections:
1. Set up universal links
The return link is separate from your redirect URI, and it uses applinks instead of webcredentials. To receive it as a universal link:
- In Xcode, select your app target, go to Signing & Capabilities, then add the Associated Domains capability.
- Add an
applinks:entry for the host of the return link, for exampleapplinks:example.com. - Check that the host publishes an
apple-app-site-associationfile that lists your app ID (<TEAM_ID>.<BUNDLE_ID>) and the path of the return link:- If Signicat manages the host, send us your Team ID and bundle ID by creating a support ticket in the Signicat Dashboard. We publish the file for you.
- If you manage the host, see Supporting associated domains in the Apple developer documentation.
2. Forward universal links to the SDK
Pass the universal links that your app receives to handle(url:). It returns either:
truewhen the SDK used the link for the running login.falsewhen your app should handle the link itself.
- SwiftUI
- UIKit
WindowGroup {
ContentView()
.onOpenURL { url in
if !SignicatOIDCClient.shared.handle(url: url) {
// Handle other links in your app.
}
}
}
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let url = userActivity.webpageURL else { return }
if !SignicatOIDCClient.shared.handle(url: url) {
// Handle other links in your app.
}
}
3. Strict validation of return link
Treat the return link as untrusted input because it comes from outside your app. At a minimum, you must:
- Accept only the exact host and path you registered, over HTTPS.
- Reject links with unexpected query parameters.
- Handle the case where the identity provider returns an error instead of a result.
- Reject links that fail any check. Do not forward them.
Pass an appLinkHandler to login(). The SDK calls it with each link that your app passes to handle(url:) during the login. The handler must do one of the following:
- Return
nilif the link is not part of the flow.handle(url:)then returnsfalse. - Return the URL that continues the flow. The SDK follows its redirects.
- Throw
SignicatOIDCError.appLinkHandlerFailed(_:)if the link is invalid.login()then fails with theappLinkHandlerFailederror code.NoteIf you throw an error that is not a
SignicatOIDCError, thenlogin()fails withauthorizationFailed.
let session = try await SignicatOIDCClient.shared.login(appLinkHandler: { url in
guard isReturnLink(url) else { return nil }
return try continuationURL(from: url)
})
Redirect handling
During an app-to-app login, the SDK only follows HTTPS redirects on the host of the authorisation endpoint and its subdomains. It passes any other URL to iOS to open the identity provider's app.
This means that:
- The URL that your handler returns must be on the host of the authorisation endpoint or one of its subdomains.
- Every step must return a redirect. If a step returns a page instead,
login()fails with theauthorizationFailederror code. - If no installed app can open a URL with a custom URL scheme,
login()fails with theauthorizationFailederror code. - If no installed app opens an HTTPS link, iOS opens it in the end-user's default browser. The login continues only if your app receives the return link. Until then, the waiting screen stays open, and the end-user can close it.
- If the end-user closes the waiting screen,
login()fails with theauthorizationCancellederror code.
Demo app example
The demo app includes examples of complete app-to-app flows so that you can test them and see how they work. These flows include the following:
- OIDC configuration.
- Code that receives and validates the return link.
- An
appLinkHandlerthat returns the URL to continue the flow. - Associated domain entitlements.
You can use the example as a model for how to implement your own app-to-app flow, but you must check the documentation of the identity provider that you want to integrate with in addition to the SDK documentation.
This is because each identity method defines its own return link format and its own way of resuming the flow.
To learn more, see the following links: