Auth0.OidcClient.iOS

ASWebAuthenticationSession

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

bash

gh api repos/auth0/auth0-oidc-client-net/releases --jq '[.[] | select(.tag_name | startswith("ios-")) | .tag_name | ltrimstr("ios-")] | .[0]'

Use the returned version in all dependency lines instead of any hardcoded version below.

• .NET 8.0 SDK or later (.NET 9 also supported — use

  net9.0-ios

  target framework)
• JetBrains Rider or VS Code with C# Dev Kit (with iOS workload)
• macOS with Xcode 15+
• iOS 14.0+ deployment target
• Auth0 account with a Native application configured
• Node.js 20+ (for Auth0 CLI automated setup)

Agent instruction: Before starting, examine the user's project:

1. Identify the .NET version from the

   .csproj

   file (

   TargetFramework

   )
2. Check for existing authentication implementations — search for existing login/logout handlers and hook into them if found (reuse existing UI elements like login buttons rather than creating duplicates)
3. Note the project's Bundle Identifier from

   Info.plist

   or

   .csproj

4. Look for existing

   Auth0Client

   or

   Auth0ClientOptions

   usage to avoid duplicate configuration

1. Install SDK:

   dotnet add package Auth0.OidcClient.iOS

2. Configure Auth0: See Setup Guide for automatic or manual configuration.
3. Integrate authentication: Add

   Auth0Client

   instantiation, register the URL scheme in

   Info.plist

   , and wire login/logout to UI actions.
4. Handle callback: Implement

   OpenUrl

   in

   AppDelegate

   and call

   ActivityMediator.Instance.Send(url.AbsoluteString)

   .
5. Build and verify:

   dotnet build

Agent instruction: When writing the Auth0Client configuration:

• The iOS SDK does NOT require passing an Activity context — just

  new Auth0Client(options)

  .
• Always set

  Scope = "openid profile email offline_access"

  — the

  offline_access

  scope is required to receive refresh tokens, enabling silent token renewal without re-prompting the user.
• The callback URL is automatically derived from the Bundle Identifier:

  {BundleId}://{domain}/ios/{BundleId}/callback

  .
• The Bundle Identifier must be registered as a URL scheme in

  Info.plist

  .
• The

  AppDelegate

  must handle

  OpenUrl

  and call

  ActivityMediator.Instance.Send(url.AbsoluteString)

  .
• Store tokens securely: After successful login, persist

  AccessToken

  and

  RefreshToken

  using iOS Keychain (via

  Security

  framework or a wrapper like

  KeychainAccess

  ). Never store tokens in

  UserDefaults

  or in-memory variables only.

After writing configuration and code, verify the build succeeds:

bash

dotnet build

If the build fails, attempt to fix the issue. After 5-6 failed attempts, ask the user for help.

LoginAsync()

1. SDK constructs the

   /authorize

   URL with PKCE parameters (code verifier + challenge)
2. ASWebAuthenticationSession opens showing the Auth0 login page
3. User authenticates (login form, social connections, MFA, etc.)
4. Auth0 redirects to the native callback URL:

   {BundleId}://{domain}/ios/{BundleId}/callback

5. iOS intercepts the URL scheme and delivers it to

   AppDelegate.OpenUrl

6. ActivityMediator.Instance.Send(url.AbsoluteString)

   completes the token exchange
7. SDK returns

   LoginResult

   with access token, ID token, refresh token, and user claims

YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback

YOUR_BUNDLE_IDENTIFIER

com.mycompany.myapplication

com.mycompany.myapp://tenant.us.auth0.com/ios/com.mycompany.myapp/callback

Note: Some Auth0 native SDKs use

https://{domain}/ios/{bundleId}/callback

or

{bundleId}.auth0://{domain}/ios/{bundleId}/callback

as the callback URL format. The .NET iOS SDK uses the Bundle Identifier directly as the URL scheme.

1. Registered in Auth0 Dashboard under Allowed Callback URLs and Allowed Logout URLs
2. Registered as a URL scheme in

   Info.plist

   under

   CFBundleURLSchemes

• Auth0.OidcClient.iOS

  package installed (latest stable version)

• Auth0Client

  configured with Domain, ClientId, and

  Scope = "openid profile email offline_access"

• URL scheme registered in

  Info.plist

  matching the Bundle Identifier

• AppDelegate.OpenUrl

  implemented with

  ActivityMediator.Instance.Send(url.AbsoluteString)

• Callback URL added to Auth0 Dashboard Allowed Callback URLs and Allowed Logout URLs
• Tokens stored securely using iOS Keychain (

  Security

  framework with

  SecKeyChain.Add

  )
• Login/logout flow working
• Build succeeds with no errors

• Setup Guide — Auth0 tenant configuration, SDK installation, Info.plist URL scheme setup
• Integration Patterns — Login/logout flows, token access, user profile, error handling
• API Reference & Testing — Full

  Auth0ClientOptions

  reference, claims, testing checklist, troubleshooting

Agent instruction: Remind the user to test on a physical device in addition to simulators. Some WebAuth/ASWebAuthenticationSession behaviors may differ on physical devices vs. simulators. Test the full login → callback → token flow on real hardware before shipping.

• Login flow: ASWebAuthenticationSession opens → authenticate → returns to app
• Callback:

  OpenUrl

  fires in AppDelegate with correct URL
• Logout flow: Browser opens → session cleared → returns to app
• Cancel: User dismisses sheet → app handles

  UserCancel

  gracefully

• auth0-maui — .NET MAUI cross-platform apps (iOS + Android + Windows)
• auth0-net-android — .NET Android-only apps
• auth0-swift — iOS-only Swift apps
• auth0-aspnetcore-authentication — ASP.NET Core server-side web apps
• auth0-aspnetcore-api — ASP.NET Core Web API with JWT validation

using Auth0.OidcClient;

var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "YOUR_AUTH0_DOMAIN",
    ClientId = "YOUR_AUTH0_CLIENT_ID",
    Scope = "openid profile email offline_access"
});

var loginResult = await client.LoginAsync();
BrowserResultType browserResult = await client.LogoutAsync();

Agent instruction: Always include

offline_access

in the scope to enable refresh tokens. This allows the app to silently refresh access tokens without forcing the user to re-authenticate.

Agent instruction: After login, always persist tokens to the iOS Keychain using the

Security

framework (

SecKeyChain.Add

with

SecAccessible.WhenUnlockedThisDeviceOnly

). Never store tokens in

UserDefaults

or leave them only in memory. Clear tokens on logout. See Integration Patterns for the full

SecureTokenStorage

helper class.

1. Info.plist: Add

   CFBundleURLSchemes

   entry matching the Bundle Identifier
2. AppDelegate: Override

   OpenUrl

   and call

   ActivityMediator.Instance.Send(url.AbsoluteString)

• .NET Android & iOS Quickstart
• GitHub Repository
• NuGet Package — Auth0.OidcClient.iOS
• SDK API Documentation
• Auth0 Native App Documentation