📚 Documentation • 🚀 Getting Started • 💻 Sample App • 📃 Support Policy • 💬 Feedback

Documentation

Composable UI building blocks for MFA enrollment and verification on iOS, built with SwiftUI Compose. This library provides ready-to-use components that integrate seamlessly with Auth0's authentication flows.

• Sample App
• API Documentation
• Theme System — customise colours, typography, spacing, radii, and component sizes

Features

This library provides ready-to-use UI components for multi-factor authentication:

• 🔐 TOTP (Time-based One-Time Password) - Authenticator app support with QR code enrollment
• 📱 Push Notifications - Secure push-based authentication
• 💬 SMS OTP - Phone number verification via one-time codes
• 📧 Email OTP - Email-based verification
• 🔑 Recovery Codes - Backup authentication codes for account recovery
• 🔐 Passkeys - Passwordless authentication using FIDO2/WebAuthn standards (Requires iOS 16.6+, macOS 13.5+, visionOS 1.0+)

All components are built on top of the Auth0 Swift SDK and integrate with Auth0's My Account APIs.

⚠️ My Account APIs Required - This SDK requires My Account APIs which are currently in early access. Please reach out to Auth0 support to enable My Account APIs for your tenant.

⚠️ BETA RELEASE - This SDK is currently in beta. APIs may change before the stable release.

Getting Started

Requirements

• iOS 16.0+
• macOS 14.0+
• visionOS 1.0+
• Swift 6.0+
• Xcode 26.0+

Installation

CocoaPods

Add the following to your Podfile:

pod 'Auth0UniversalComponents'

Then run pod install.

Swift Package Manager

Add the following to your Package.swift:

.package(url: "https://github.com/auth0/ui-components-ios.git", from: "1.0.0")

Or use Xcode: File → Add Packages → Enter the repository URL.

Carthage

Add the following to your Cartfile:

github "auth0/ui-components-ios"

Configure the SDK

Step 1: Configure Auth0 Credentials

You can configure the SDK in two ways:

Option A: Using Auth0.plist (Recommended)

1. Create Auth0.plist in your Xcode project:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Domain</key>
    <string>YOUR_AUTH0_DOMAIN.auth0.com</string>
    <key>ClientId</key>
    <string>YOUR_AUTH0_CLIENT_ID</string>
</dict>
</plist>

2. Ensure Auth0.plist is added to your target's Build Phases.

Option B: Programmatic Configuration

Pass your credentials directly during initialization.

Step 2: Initialize Auth0Dependencies in Your App

Initialize Auth0Dependencies in your app's entry point. This must be done before using any UI components.

import SwiftUI
import Auth0UniversalComponents

// Custom token provider
struct YourTokenProvider: TokenProvider {
    func fetchAPICredentials(audience: String, scope: String) async throws -> APICredentials {
        // Your custom logic to retrieve access token
    }
}

@main
struct MyApp: App {
    init() {
        // Initialize with Auth0.plist
        Auth0UniversalComponentsSDKInitializer.initialize(tokenProvider: YourTokenProvider())
        // OR initialize programmatically
        //Auth0UniversalComponentsSDKInitializer.initialize(session: URLSession = .shared,
        //                                           bundle: Bundle = .main,
        //                                           domain: "your-auth0-domain",
        //                                           clientId: "your_client_id",
        //                                           audience: "https://your-auth0-domain.auth0.com/me/",
        //                                           tokenProvider: YourTokenProvider())
    }

    var body: some Scene {
        WindowGroup {
            NavigationStack {
                MyRootView()
                    .navigationDestination(for: AppRoute.self) { route in
                        // Your app's route handler
                    }
            }
        }
    }
}

Step 3: Use UI Components

Once initialized, embed MyAccountAuthMethodsView inside your app's NavigationStack. Use .embeddedInNavigationStack() and inject your navigation path so the SDK can push its internal screens onto your stack:

import SwiftUI
import Auth0UniversalComponents

@main
struct MyApp: App {
    @StateObject private var router = Router<AppRoute>()

    var body: some Scene {
        WindowGroup {
            NavigationStack(path: $router.path) {
                MyRootView()
                    .navigationDestination(for: AppRoute.self) { route in
                        switch route {
                        case .authMethods:
                            MyAccountAuthMethodsView()
                                .embeddedInNavigationStack()
                        }
                    }
            }
            .environment(\.hostNavigationPath, $router.path)
            .environmentObject(router)
        }
    }
}

Universal Login Step-Up Flow

This SDK uses Universal Login for step-up authentication flows. When an MFA-required error is encountered, the SDK automatically initiates a step-up flow to allow users to complete the required MFA challenge.

Prerequisites for Universal Login

To enable the step-up flow, configure the following in your Auth0 Tenant:

1. Associated Domains - Add your app's associated domain to your Auth0 application settings
2. Callback URLs - Configure the following in your Auth0 application:
   • Add your app's callback URL (e.g., com.yourcompany.yourapp://YOUR_AUTH0_DOMAIN/ios/com.yourcompany.yourapp/callback)
   • Ensure it matches your app's URL scheme and associated domain configuration

Configuration Steps

1. In your Xcode project, enable Associated Domains capability
2. Add your domain entitlement (e.g., applinks:YOUR_AUTH0_DOMAIN.auth0.com)
3. Configure your Auth0 application settings with the callback URL
4. The SDK will automatically handle the Universal Login flow when MFA is required

For more detailed information on Universal Login configuration, associated domains, and callback URL setup, refer to the Auth0.swift SDK documentation.

Components

Authentication Methods

Display and manage user's authentication methods.

MyAccountAuthMethodsView()

Allows users to:

• View connected authenticators
• Enroll in new authentication methods (TOTP, Push, Email, SMS, Recovery Code)
• Remove authentication methods

Screenshots

Authentication Methods	Manage Auth Methods
View connected authenticators	Delete/Add MFA

Sample App

This repository includes a sample app (AppUIComponents target) that demonstrates how to use the Auth0 UI Components SDK. You can use the sample app to explore the SDK's features and test the MFA components.

Running the Sample App

1. Clone the repository:

   git clone https://github.com/auth0/ui-components-ios.git
   cd ui-components-ios

2. Install dependencies using Carthage:

   carthage bootstrap --use-xcframeworks

Option 1: Automated Setup (Recommended)

Use the bootstrap script to automatically create all required Auth0 resources and configure the sample app.

Prerequisites:

• Node.js 20+
• Auth0 CLI

1. Login to Auth0 CLI with the required scopes:

   auth0 login --scopes "create:client_grants,update:client_grants,delete:client_grants,create:connections,create:resource_servers,create:roles,create:users,read:client_keys,read:client_grants,read:clients,read:connections,read:resource_servers,read:roles,update:clients,update:connections,read:connection_profiles,create:connection_profiles,update:connection_profiles,create:user_attribute_profiles,update:user_attribute_profiles,read:user_attribute_profiles,update:resource_servers,update:roles,update:tenant_settings,update:prompts"
   auth0 tenants list  # verify your tenant shows Active

2. Run the bootstrap script:

   cd scripts
   npm install
   npm run auth0:bootstrap <your-tenant-domain>

   This will:

   • Create a Native application configured for the iOS sample app
   • Enable the My Account API and create a Client Grant with MFA scopes
   • Create a database connection and admin role
   • Configure tenant settings for MFA
   • Update Auth0.plist with the generated credentials

Option 2: Manual Setup

1. Create a Native application in your Auth0 tenant and note the Client ID and Domain.

2. Configure Allowed Callback URLs in your Auth0 Dashboard. Add:

https://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback, YOUR_BUNDLE_IDENTIFIER://YOUR_AUTH0_DOMAIN/ios/YOUR_BUNDLE_IDENTIFIER/callback

Replace `{scheme}` and `{domain}` with your values.

3. **Configure Auth0 credentials:**

**Important:** The `Auth0.plist` file is required for the sample app to build and run. You need to create this file.

- Create `AppUIComponents/Auth0.plist` in your Xcode project with your Auth0 tenant information:
  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  <plist version="1.0">
  <dict>
      <key>Domain</key>
      <string>YOUR_AUTH0_DOMAIN.auth0.com</string>
      <key>ClientId</key>
      <string>YOUR_AUTH0_CLIENT_ID</string>
      <key>Audience</key>
      <string>https://YOUR_AUTH0_DOMAIN.auth0.com/api/v2/</string>
  </dict>
  </plist>
  ```
- Ensure the file is added to the `AppUIComponents` target in Build Phases

4. **Open the project in Xcode:**
```bash
open Auth0UniversalComponents.xcodeproj

5. Select the AppUIComponents target from the scheme dropdown

6. Build and run the app:

   Running on iOS Simulator

   • Select any iOS simulator from the device dropdown (e.g., iPhone 15 Pro)
   • Press Cmd + R or click the Run button
   • The app will build and launch in the simulator

   Running on a Physical Device

   To run the sample app on a physical device, you need to:

   • Apple Developer Account: Your device must be registered in your Apple Developer account
   • Update Bundle Identifier:
     1. Select the AppUIComponents target in Xcode
     2. Go to the "Signing & Capabilities" tab
     3. Update the bundle identifier to match your provisioning profile (e.g., com.yourcompany.AppUIComponents)
   • Code Signing: Ensure your team is selected and provisioning profile is valid
   • Connect your device via USB and select it from the device dropdown
   • Press Cmd + R or click the Run button

   Note: Without a valid provisioning profile and registered device, you will encounter code signing errors when attempting to run on a physical device.

Portions of this SDK may have AI-assisted or generated code.

Support Policy

This Policy defines the extent of the support for Xcode, Swift, and platform (iOS, macOS, tvOS, and watchOS) versions in Auth0.swift.

Xcode

The only supported versions of Xcode are those that can be currently used to submit apps to the App Store. Once a Xcode version becomes unsupported, dropping it from Auth0.swift will not be considered a breaking change, and will be done in a minor release.

Swift

The minimum supported Swift minor version is the one released with the oldest-supported Xcode version. Once a Swift minor becomes unsupported, dropping it from Auth0.swift will not be considered a breaking change, and will be done in a minor release.

Platforms

We support only the last four major versions of any platform, including the current major version.

Once a platform version becomes unsupported, dropping it from ui-components-ios will not be considered a breaking change, and will be done in a minor release. For example, iOS 14 will cease to be supported when iOS 18 gets released, and ui-components-ios will be able to drop it in a minor release.

In the case of macOS, the yearly named releases are considered a major platform version for the purposes of this Policy, regardless of the actual version numbers.

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines
• ui-components-ios's contribution guide

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

---

Auth0 is an easy-to-implement, adaptable authentication and authorization platform. To learn more check out Why Auth0?

This project is licensed under the Apache License 2.0. See the LICENSE file for more info.
Copyright 2025 Okta, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
    http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.