iOS/iPadOS - Native Apps

Use this page to implement Clever SSO in a native iOS app with Universal Links.

🚧

Custom URL schemes are not recommended

If your app uses custom URL schemes to launch on iOS, update your implementation to use Universal Links instead.

To learn more about custom URL schemes, see https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app.

Overview

If you have a native iOS app, use Universal Links for Clever SSO.

Universal Links let iOS open your native app when a user navigates to one of your URLs on a mobile device. If your app is not installed, iOS opens that URL in the browser instead.

To support Universal Links, register your domain in your app entitlements and host the required JSON verification file on that domain.

For Apple’s implementation details, see:

• iOS Universal Links

🚧

Clever iOS SDK

The Clever iOS SDK is deprecated and is not required to implement Log in with Clever in a native iOS app.

To migrate from the SDK-based flow, see Log in with Clever ("LIWC") iOS Update.

SSO from the Clever Portal

Use this flow when the user starts in the Clever Portal and selects your application.

1. The user selects your app icon in the Clever Portal.
2. Clever redirects the user to your primary redirect URL with the standard authentication parameters.
3. Because your redirect URL is registered as a Universal Link, iOS opens your native app and passes the authorization code to it.
4. Your native app sends the authorization code to your server.
5. Your server exchanges the authorization code for a token and determines which account to sign in.
6. Your server returns the information your app needs to start an authenticated session.

SSO from a Log in with Clever button

Use this flow when the user starts from a "Log in with Clever" button inside your native app.

🚧

Updated LIWC flow for iOS

The original iOS SDK flow is deprecated in response to Apple’s authentication guidance.

For migration details, see Log in with Clever ("LIWC") iOS Update.

1. The user selects the "Log in with Clever" option from your app’s login page.
2. Your app opens a browser-based authentication session, such as ASWebAuthenticationSession, to start the Clever authentication flow.
3. After authentication, Clever redirects the user to a URL that you have registered as a Universal Link.
4. Your native app receives the authorization code from that redirect.
5. Your native app sends the authorization code to your server.
6. Your server exchanges the code for a token, identifies the correct user account, and returns the session information your app needs.

Handle duplicate callback processing on iOS

When your redirect URL is also a Universal Link, Safari can continue loading the callback URL before iOS finishes handing the user off to your app. In some implementations, both Safari and the native app then send the same authorization code to your backend.

Clever authorization codes are single-use. If your backend exchanges the same code twice, the first request succeeds and the second can fail with invalid_grant.

This can appear as:

• intermittent native login failures
• the native app opening without an authenticated session
• several-second delays during the Safari-to-app handoff

To avoid this:

1. Make authorization code processing single-consumer on your backend.
2. Deduplicate callback requests by authorization code for a short time window.
3. Do not treat a second callback for the same code as a new login attempt.
4. Log duplicate callback requests so you can diagnose iOS handoff issues.