| title | description | interactive | files | github | locale | ||||
|---|---|---|---|---|---|---|---|---|---|
Add Login to Your iOS or macOS Application |
This guide demonstrates how to integrate Auth0 with any iOS / macOS app using the Auth0.swift SDK. |
true |
|
en-US |
This guide demonstrates how to add authentication and access user profile information in any iOS / macOS app using the Auth0.swift SDK.
To use this quickstart, you need to:
Sign up for a free Auth0 account or log in to Auth0.
Have an existing iOS / macOS app that you want to integrate. Alternatively, you can view or download a sample app after logging in.
To use Auth0 services, you need an application set up in the Auth0 Dashboard. The Auth0 application is where you will configure how you want authentication to work for the app you are developing.
Use the interactive selector to create a new Auth0 application or select an existing Native Auth0 application. Auth0 assigns every application an alphanumeric, unique Client ID that your app uses to call Auth0 APIs through the SDK.
Any settings you configure using this quickstart automatically update your Auth0 application in the Dashboard, which is where you can manage your applications in the future.
If you would rather explore a complete configuration, you can view a sample app instead.
Auth0 invokes the callback and logout URLs to redirect users back to your app. Auth0 invokes the callback URL after authenticating the user and the logout URL after removing the session cookie. If you do not set the callback and login URLs, users will not be able to log in and out of the app, and your app will produce an error.
On iOS 17.4+ and macOS 14.4+ it is possible to use Universal Links as callback and logout URLs. When enabled, Auth0.swift will fall back to using a custom URL scheme on older iOS / macOS versions.
This feature requires Xcode 15.3+ and a paid Apple Developer account.
Add the following URLs to Callback URLs and Logout URLs, depending on the platform of your app. If you have a custom domain, use this instead of your Auth0 tenant’s domain.
Use the interactive selector to create a new Auth0 application or select an existing Native Auth0 application. Auth0 assigns every application an alphanumeric, unique Client ID that your app uses to call Auth0 APIs through the SDK.
Any settings you configure using this quickstart automatically update your Auth0 application in the Dashboard, which is where you can manage your applications in the future.
If you would rather explore a complete configuration, you can view a sample app instead.
Auth0 invokes the callback and logout URLs to redirect users back to your app. Auth0 invokes the callback URL after authenticating the user and the logout URL after removing the session cookie. If you do not set the callback and login URLs, users will not be able to log in and out of the app, and your app will produce an error.
::: note On iOS 17.4+ and macOS 14.4+ it is possible to use Universal Links as callback and logout URLs. When enabled, Auth0.swift will fall back to using a custom URL scheme on older iOS / macOS versions.
Whenever possible, Auth0 recommends using Universal Links as a secure way to link directly to content within your app. Custom URL schemes can be subject to client impersonation attacks.
This feature requires Xcode 15.3+ and a paid Apple Developer account. :::
Add the following URLs to Callback URLs and Logout URLs, depending on the platform of your app. If you have a custom domain, use this instead of your Auth0 tenant’s domain.
https://${account.namespace}/ios/YOUR_BUNDLE_IDENTIFIER/callback,
YOUR_BUNDLE_IDENTIFIER://${account.namespace}/ios/YOUR_BUNDLE_IDENTIFIER/callback
https://${account.namespace}/macos/YOUR_BUNDLE_IDENTIFIER/callback,
YOUR_BUNDLE_IDENTIFIER://${account.namespace}/macos/YOUR_BUNDLE_IDENTIFIER/callback
For example, if your iOS bundle identifier was com.example.MyApp and your Auth0 domain was example.us.auth0.com, then this value would be:
https://example.us.auth0.com/ios/com.example.MyApp/callback,
com.example.MyApp://example.us.auth0.com/ios/com.example.MyApp/callback
::: warning This step requires a paid Apple Developer account. It is needed to use Universal Links as callback and logout URLs. Skip this step to use a custom URL scheme instead. :::
Go to the settings page of your Auth0 application, scroll to the end, and open Advanced Settings > Device Settings. In the iOS section, set Team ID to your Apple Team ID, and App ID to your app's bundle identifier.
This will add your app to your Auth0 tenant's apple-app-site-association file.
In Xcode, go to the Signing and Capabilities tab of your app's target settings, and press the + Capability button. Then select Associated Domains.
Next, add the following entry under Associated Domains:
webcredentials:${account.namespace}
If you have a custom domain, use this instead of your Auth0 tenant’s domain.
::: note For the associated domain to work, your app must be signed with your team certificate even when building for the iOS simulator. Make sure you are using the Apple Team whose Team ID is configured in the settings page of your Auth0 application. :::
Open the following menu item in Xcode:
File > Add Package Dependencies...
In the Search or Enter Package URL search box enter this URL:
https://github.com/auth0/Auth0.swift
Then, select the dependency rule and press Add Package.
For further reference on SPM, check its official documentation.
Add the following line to your Podfile:
pod 'Auth0', '~> 2.0'
Then, run pod install.
For further reference on Cocoapods, check their official documentation.
Add the following line to your Cartfile:
github "auth0/Auth0.swift" ~> 2.0
Then, run carthage bootstrap --use-xcframeworks.
For further reference on Carthage, check their official documentation.
The Auth0.swift SDK needs your Auth0 domain and Client ID. You can find these values in the settings page of your Auth0 application.
domain: The domain of your Auth0 tenant. If you have a custom domain, use this instead of your Auth0 tenant’s domain.
Client ID: The alphanumeric, unique ID of the Auth0 application you set up earlier in this quickstart.
Create a plist file named Auth0.plist in your app bundle containing the Auth0 domain and Client ID values.
You can also configure the SDK programmatically. Check the README to learn more.
You configured the Auth0.swift SDK. Run your app to verify that it is not producing any errors related to the SDK.
Add the following line to your Cartfile:
github "auth0/Auth0.swift" ~> 2.0
Then, run carthage bootstrap --use-xcframeworks.
::: note For further reference on Carthage, check their official documentation. :::
The Auth0.swift SDK needs your Auth0 domain and Client ID. You can find these values in the settings page of your Auth0 application.
- domain: The domain of your Auth0 tenant. If you have a custom domain, use this instead of your Auth0 tenant’s domain.
- Client ID: The alphanumeric, unique ID of the Auth0 application you set up earlier in this quickstart.
Create a plist file named Auth0.plist in your app bundle containing the Auth0 domain and Client ID values.
::: note You can also configure the SDK programmatically. Check the README to learn more. :::
::::checkpoint :::checkpoint-default You configured the Auth0.swift SDK. Run your app to verify that it is not producing any errors related to the SDK. :::
:::checkpoint-failure If your app produces errors related to the SDK:
- Make sure you selected the correct Auth0 application
- Verify you saved your URL updates
- Ensure you set the Auth0 domain and Client ID correctly
Still having issues? Check out our documentation or visit our community page to get more help. ::: ::::
Import the Auth0 module in the file where you want to present the login page. Then, present the Universal Login page in the action of your Login button.
You can use async/await or Combine instead of the callback-based API. Check the README to learn more.
Press the Login button and verify that:
An alert box shows up asking for consent.
Choosing Continue opens the Universal Login page in a Safari modal.
You can log in or sign up using a username and password or a social provider.
The Safari modal closes automatically afterward.
If login fails or produces errors:
Verify you entered the correct callback URL
Ensure you set the Auth0 domain and Client ID correctly
Still having issues? Check out our documentation or visit our community page to get more help.
Now that you can log in to your app, you need a way to log out. In the action of your Logout button, call the clearSession() method to clear the Universal Login session cookie.
Press the Logout button and verify that:
An alert box shows up asking for consent.
Choosing Continue opens a page in a Safari modal.
The Safari modal closes automatically soon after.
If logout fails or produces errors:
Verify you entered the correct callback URL
Ensure you set the Auth0 domain and Client ID correctly
Still having issues? Check out our documentation or visit our community page to get more help.
The Credentials instance you obtained after logging in includes an ID token. The ID token contains the profile information associated with the logged-in user, such as their email and profile picture. You can use these details to personalize the user interface of your app.
The Auth0.swift SDK includes a utility for decoding JWTs like the ID token. Start by importing the JWTDecode module in the file where you want to access the user profile information. Then, use the decode(jwt:) method to decode the ID token and access the claims it contains.
You can retrieve the latest user information with the userInfo(withAccessToken:) method. Check the EXAMPLES to learn more.
Verify that you can access the email, picture, or any other claim after you have logged in.
If you cannot access the user information:
Verify you imported the
JWTDecodemodule where you invoke thedecode(jwt:)methodMake sure you spelled your claims correctly
Still having issues? Check out our documentation or visit our community forums to get more help.