For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

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:

  1. Your app requests the identity provider's app through the acrValues property of your OIDCConfiguration. For details, see the Configuration reference section on the iOS Set up the SDK page.
  2. Your app calls login(appLinkHandler:), and the SDK starts the OIDC flow.
  3. 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.
  4. The identity provider's app opens a universal link to your app. Your app passes the link to handle(url:).
  5. The SDK passes the link to your appLinkHandler, which validates it and returns the URL that continues the flow.
  6. 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:

The return link is separate from your redirect URI, and it uses applinks instead of webcredentials. To receive it as a universal link:

  1. In Xcode, select your app target, go to Signing & Capabilities, then add the Associated Domains capability.
  2. Add an applinks: entry for the host of the return link, for example applinks:example.com.
  3. Check that the host publishes an apple-app-site-association file that lists your app ID (<TEAM_ID>.<BUNDLE_ID>) and the path of the return link:

Pass the universal links that your app receives to handle(url:). It returns either:

  • true when the SDK used the link for the running login.
  • false when your app should handle the link itself.
Example: Forward universal links in SwiftUI
WindowGroup {
ContentView()
.onOpenURL { url in
if !SignicatOIDCClient.shared.handle(url: url) {
// Handle other links in your app.
}
}
}

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 nil if the link is not part of the flow. handle(url:) then returns false.
  • Return the URL that continues the flow. The SDK follows its redirects.
  • Throw SignicatOIDCError.appLinkHandlerFailed(_:) if the link is invalid. login() then fails with the appLinkHandlerFailed error code.
    Note

    If you throw an error that is not a SignicatOIDCError, then login() fails with authorizationFailed.

Example: Log in with an app link handler
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 the authorizationFailed error code.
  • If no installed app can open a URL with a custom URL scheme, login() fails with the authorizationFailed error 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 the authorizationCancelled error 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 appLinkHandler that 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: