diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b014abbb..48a1e447 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -> **Note** +> [!IMPORTANT] > Tests must be added for all new functionality. Existing tests must be updated for all changed/fixed functionality, where applicable. All tests must complete without errors. All new functionality must be documented as well. ## Environment setup diff --git a/EXAMPLES.md b/EXAMPLES.md index 8e28a392..c5f19adf 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -43,7 +43,7 @@ Auth0 } ``` -> **Note** +> [!NOTE] > The `screen_hint` parameter will work with the **New Universal Login Experience** without any further configuration. If you are using the **Classic Universal Login Experience**, you need to customize the [login template](https://manage.auth0.com/#/login_page) to look for this parameter and set the `initialScreen` [option](https://github.com/auth0/lock#database-options) of the `Auth0Lock` constructor.
@@ -144,22 +144,11 @@ Note that this custom `URLSession` instance will be used when communicating with Auth0.swift automatically [validates](https://auth0.com/docs/secure/tokens/id-tokens/validate-id-tokens) the ID token obtained from Web Auth login, following the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html). This ensures the contents of the ID token have not been tampered with and can be safely used. -#### Custom Domains - -Users of Auth0 Private Cloud with custom domains still on the [legacy behavior](https://auth0.com/docs/migrate-private-cloud-custom-domains) need to specify a custom issuer to match the Auth0 Domain when performing Web Auth login. Otherwise, the ID token validation will fail. - -```swift -Auth0 - .webAuth() - .issuer("https://YOUR_AUTH0_DOMAIN/") - // ... -``` - ### Web Auth errors Web Auth will only produce `WebAuthError` error values. You can find the underlying error (if any) in the `cause: Error?` property of the `WebAuthError`. Not all error cases will have an underlying `cause`. Check the [API documentation](https://auth0.github.io/Auth0.swift/documentation/auth0/webautherror) to learn more about the error cases you need to handle, and which ones include a `cause` value. -> **Warning** +> [!WARNING] > Do not parse or otherwise rely on the error messages to handle the errors. The error messages are not part of the API and can change. Run a switch statement on the [error cases](https://auth0.github.io/Auth0.swift/documentation/auth0/webautherror/#topics) instead, which are part of the API. [Go up ⤴](#examples) @@ -183,8 +172,8 @@ The Credentials Manager utility allows you to securely store and retrieve the us let credentialsManager = CredentialsManager(authentication: Auth0.authentication()) ``` -> **Warning** -> The Credentials Manager is not thread-safe, except for the `credentials()` and `renew()` methods. Do not call its non thread-safe methods and properties from different threads without proper synchronization. +> [!CAUTION] +> The Credentials Manager is not thread-safe, except for its `credentials()` and `renew()` methods. To avoid concurrency issues, do not call its non thread-safe methods and properties from different threads without proper synchronization. ### Store credentials @@ -207,7 +196,7 @@ guard credentialsManager.canRenew() else { // Retrieve the stored credentials ``` -> **Note** +> [!NOTE] > You need to request the `offline_access` [scope](https://auth0.com/docs/get-started/apis/scopes) when logging in to get a refresh token from Auth0. Make sure that your Auth0 application has the **refresh token** [grant enabled](https://auth0.com/docs/get-started/applications/update-grant-types). If you are also specifying an audience value, make sure that the corresponding Auth0 API has the **Allow Offline Access** [setting enabled](https://auth0.com/docs/get-started/apis/api-settings#access-settings). #### If you are not using refresh tokens @@ -264,13 +253,13 @@ credentialsManager ```
-> **Note** +> [!NOTE] > You need to request the `offline_access` [scope](https://auth0.com/docs/get-started/apis/scopes) when logging in to get a refresh token from Auth0. Make sure that your Auth0 application has the **refresh token** [grant enabled](https://auth0.com/docs/get-started/applications/update-grant-types). If you are also specifying an audience value, make sure that the corresponding Auth0 API has the **Allow Offline Access** [setting enabled](https://auth0.com/docs/get-started/apis/api-settings#access-settings). -> **Warning** +> [!CAUTION] > Do not call `store(credentials:)` afterward. The Credentials Manager automatically persists the renewed credentials. Since this method is thread-safe and `store(credentials:)` is not, calling it anyway can cause concurrency issues. -> **Warning** +> [!CAUTION] > To ensure that no concurrent renewal requests get made, do not call this method from multiple Credentials Manager instances. The Credentials Manager cannot synchronize requests across instances. ### Renew stored credentials @@ -318,13 +307,13 @@ credentialsManager ``` -> **Note** +> [!NOTE] > You need to request the `offline_access` [scope](https://auth0.com/docs/get-started/apis/scopes) when logging in to get a refresh token from Auth0. Make sure that your Auth0 application has the **refresh token** [grant enabled](https://auth0.com/docs/get-started/applications/update-grant-types). If you are also specifying an audience value, make sure that the corresponding Auth0 API has the **Allow Offline Access** [setting enabled](https://auth0.com/docs/get-started/apis/api-settings#access-settings). -> **Warning** +> [!CAUTION] > Do not call `store(credentials:)` afterward. The Credentials Manager automatically persists the renewed credentials. Since this method is thread-safe and `store(credentials:)` is not, calling it anyway can cause concurrency issues. -> **Warning** +> [!CAUTION] > To ensure that no concurrent renewal requests get made, do not call this method from multiple Credentials Manager instances. The Credentials Manager cannot synchronize requests across instances. ### Retrieve stored user information @@ -353,9 +342,6 @@ You can enable an additional level of user authentication before retrieving cred credentialsManager.enableBiometrics(withTitle: "Unlock with Face ID") ``` -> **Note** -> You need a real device to test biometric authentication. Biometrics are not available in simulators. - If needed, you can specify a particular `LAPolicy` to be used. For example, you might want to support Face ID or Touch ID, but also allow fallback to passcode. ```swift @@ -363,14 +349,14 @@ credentialsManager.enableBiometrics(withTitle: "Unlock with Face ID or passcode" evaluationPolicy: .deviceOwnerAuthentication) ``` -> **Note** +> [!NOTE] > Retrieving the user information with `credentialsManager.user` will not be protected by biometric authentication. ### Credentials Manager errors The Credentials Manager will only produce `CredentialsManagerError` error values. You can find the underlying error (if any) in the `cause: Error?` property of the `CredentialsManagerError`. Not all error cases will have an underlying `cause`. Check the [API documentation](https://auth0.github.io/Auth0.swift/documentation/auth0/credentialsmanagererror) to learn more about the error cases you need to handle, and which ones include a `cause` value. -> **Warning** +> [!WARNING] > Do not parse or otherwise rely on the error messages to handle the errors. The error messages are not part of the API and can change. Run a switch statement on the [error cases](https://auth0.github.io/Auth0.swift/documentation/auth0/credentialsmanagererror/#topics) instead, which are part of the API. [Go up ⤴](#examples) @@ -392,11 +378,11 @@ We recommend using [Universal Login](https://auth0.com/docs/authenticate/login/a For login or signup with username/password, the `Password` grant type needs to be enabled in your Auth0 application. If you set the grants via the Management API you should activate both `http://auth0.com/oauth/grant-type/password-realm` and `Password`. Otherwise, the Auth0 Dashboard will take care of activating both when enabling `Password`. -> **Note** -> If your Auth0 account has the **Bot Detection** feature enabled, your requests might be flagged for verification. Check how to handle this scenario in the [Bot Detection](#bot-detection) section. +> [!NOTE] +> If your Auth0 tenant has the **Bot Detection** feature enabled, your requests might be flagged for verification. Check how to handle this scenario in the [Bot Detection](#bot-detection) section. -> **Warning** -> The ID tokens obtained from Web Auth login are automatically validated by Auth0.swift, ensuring their contents have not been tampered with. **This is not the case for the ID tokens obtained from the Authentication API client.** You must [validate](https://auth0.com/docs/secure/tokens/id-tokens/validate-id-tokens) any ID tokens received from the Authentication API client before using the information they contain. +> [!WARNING] +> The ID tokens obtained from Web Auth login are automatically validated by Auth0.swift, ensuring their contents have not been tampered with. **This is not the case for the ID tokens obtained from the Authentication API client**, including the ones received when renewing the credentials using the refresh token. You must [validate](https://auth0.com/docs/secure/tokens/id-tokens/validate-id-tokens) any ID tokens received from the Authentication API client before using the information they contain. ### Login with database connection @@ -458,7 +444,7 @@ Auth0 ``` -> **Note** +> [!NOTE] > The default scope value is `openid profile email`. Regardless of the scope value specified, `openid` is always included. ### Sign up with database connection @@ -581,7 +567,7 @@ Auth0 ``` -> **Note** +> [!NOTE] > Use `startPasswordless(phoneNumber:)` to send a code to the user's phone number instead. #### 2. Login with the received code @@ -637,7 +623,7 @@ Auth0 ``` -> **Note** +> [!NOTE] > Use `login(phoneNumber:code:)` if the code was sent to the user's phone number. ### Retrieve user information @@ -748,7 +734,7 @@ Auth0 ``` -> **Note** +> [!NOTE] > You need to request the `offline_access` [scope](https://auth0.com/docs/get-started/apis/scopes) when logging in to get a refresh token from Auth0. Make sure that your Auth0 application has the **refresh token** [grant enabled](https://auth0.com/docs/get-started/applications/update-grant-types). If you are also specifying an audience value, make sure that the corresponding Auth0 API has the **Allow Offline Access** [setting enabled](https://auth0.com/docs/get-started/apis/api-settings#access-settings). ### Authentication API client configuration @@ -791,7 +777,7 @@ Auth0 The Authentication API client will only produce `AuthenticationError` error values. You can find the error information in the `info` dictionary of the error value. Check the [API documentation](https://auth0.github.io/Auth0.swift/documentation/auth0/authenticationerror) to learn more about the available `AuthenticationError` properties. -> **Warning** +> [!WARNING] > Do not parse or otherwise rely on the error messages to handle the errors. The error messages are not part of the API and can change. Use the [error types](https://auth0.github.io/Auth0.swift/documentation/auth0/authenticationerror/#topics) instead, which are part of the API. [Go up ⤴](#examples) @@ -819,11 +805,11 @@ Auth0 // ... ``` -> **Note** -> For security reasons, native mobile apps are restricted to a subset of the Management API functionality. +> [!NOTE] +> For security reasons, mobile apps are restricted to a subset of the Management API functionality. -> **Note** -> Auth0 access tokens do not support multiple custom audience values. If you are already using the API Identifier of your own API as the audience because you need to make authenticated requests to your backend, you cannot add the Management API one, and vice versa. Consider instead exposing API endpoints in your backend to perform operations that require interacting with the Management API, and then calling them from your app. +> [!IMPORTANT] +> Auth0 access tokens [do not support](https://community.auth0.com/t/how-do-i-specify-multiple-audiences/10830) multiple custom audience values. If you are already using the API Identifier of your own API as the audience because you need to make authenticated requests to your backend, you cannot add the Management API one, and vice versa. Consider instead exposing API endpoints in your backend to perform operations that require interacting with the Management API, and then calling them from your app. ### Retrieve user metadata @@ -878,7 +864,7 @@ Auth0 ``` -> **Note** +> [!TIP] > An alternative is to use a [post-login Action](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/api-object) to add the metadata to the ID token as a custom claim. ### Update user metadata @@ -1046,7 +1032,7 @@ Auth0 // ... ``` -> **Warning** +> [!CAUTION] > Set this flag only when **DEBUGGING** to avoid leaking user's credentials in the device log. With a successful authentication you'll see something similar to the following: @@ -1072,7 +1058,7 @@ Connection: keep-alive {"access_token":"...","token_type":"Bearer"} ``` -> **Note** +> [!TIP] > When troubleshooting, you can also check the logs in the [Auth0 Dashboard](https://manage.auth0.com/#/logs) for more information. [Go up ⤴](#examples) @@ -1138,7 +1124,7 @@ Auth0 ``` -> **Note** +> [!NOTE] > See the [Setting up Sign In with Apple](https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/apple-native) guide for more information about integrating Sign In with Apple with Auth0. #### Facebook Login @@ -1197,14 +1183,14 @@ Auth0 ``` -> **Note** +> [!NOTE] > See the [Setting up Facebook Login](https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/facebook-native) guide for more information about integrating Facebook Login with Auth0. ### Organizations [Organizations](https://auth0.com/docs/manage-users/organizations) is a set of features that provide better support for developers who build and maintain SaaS and Business-to-Business (B2B) apps. -> **Note** +> [!NOTE] > Organizations is currently only available to customers on our Enterprise and Startup subscription plans. #### Log in to an organization diff --git a/FAQ.md b/FAQ.md index 1f0bcd57..7f967579 100644 --- a/FAQ.md +++ b/FAQ.md @@ -17,7 +17,7 @@ Under the hood, Auth0.swift uses `ASWebAuthenticationSession` by default to perf That alert box is displayed and managed by `ASWebAuthenticationSession`, not by Auth0.swift, because by default this API will store the session cookie in the shared Safari cookie jar. This makes single sign-on (SSO) possible. According to Apple, that requires user consent. -> **Note** +> [!NOTE] > See [this blog post](https://developer.okta.com/blog/2022/01/13/mobile-sso) for a detailed overview of SSO on iOS. ### Use ephemeral sessions @@ -35,7 +35,7 @@ Auth0 Note that with `useEphemeralSession()` you don't need to call `clearSession(federated:)` at all. Just clearing the credentials from the app will suffice. What `clearSession(federated:)` does is clear the shared session cookie, so that in the next login call the user gets asked to log in again. But with `useEphemeralSession()` there will be no shared cookie to remove. -> **Note** +> [!NOTE] > `useEphemeralSession()` relies on the `prefersEphemeralWebBrowserSession` configuration option of `ASWebAuthenticationSession`. ### Use `SFSafariViewController` @@ -51,8 +51,8 @@ Auth0 } ``` -> **Note** -> Since `SFSafariViewController` does not share cookies with the Safari app, SSO will not work either. But it will keep its own cookies, so you can use it to perform SSO between your app and your website as long as you open it inside your app using `SFSafariViewController`. This also means that any feature that relies on the persistence of cookies will work as expected. +> [!IMPORTANT] +> Since `SFSafariViewController` does not share cookies with the Safari app, SSO will not work either. But it will keep its own cookies, so you can use it to perform SSO between your app and your website as long as you open it inside your app using `SFSafariViewController`. This also means that any feature that relies on the persistence of cookies –like "Remember this device"– will work as expected. If you choose to use the `SFSafariViewController` Web Auth provider, you need to perform an additional bit of setup. Unlike `ASWebAuthenticationSession`, `SFSafariViewController` will not automatically capture the callback URL when Auth0 redirects back to your app, so it's necessary to manually resume the Web Auth operation. @@ -114,7 +114,7 @@ Auth0 Otherwise, the browser modal will close right away and the user will be automatically logged in again, as the cookie will still be there. -> **Warning** +> [!WARNING] > Keeping the shared session cookie may not be an option if you have strong privacy and/or security requirements, for example in the case of a banking app. ## 3. How can I change the message in the alert box? diff --git a/README.md b/README.md index 3a755bb2..2319b090 100644 --- a/README.md +++ b/README.md @@ -28,10 +28,10 @@ Migrating from v1? Check the [Migration Guide](V2_MIGRATION_GUIDE.md). ### Requirements - iOS 13.0+ / macOS 11.0+ / tvOS 13.0+ / watchOS 7.0+ -- Xcode 14.x +- Xcode 14.x / 15.x - Swift 5.7+ -> **Note** +> [!IMPORTANT] > Check the [Support Policy](#support-policy) to learn when dropping Xcode, Swift, and platform versions will not be considered a **breaking change**. ### Installation @@ -76,7 +76,7 @@ Head to the [Auth0 Dashboard](https://manage.auth0.com/#/applications/) and crea Auth0.swift needs the **Client ID** and **Domain** of the Auth0 application to communicate with Auth0. You can find these details in the settings page of your Auth0 application. If you have a [custom domain](https://auth0.com/docs/customize/custom-domains), use your custom domain instead of the value from the settings page. -> **Warning** +> [!IMPORTANT] > Make sure that the Auth0 application type is **Native**. Otherwise, you might run into errors due to the different configuration of other application types. #### Configure Client ID and Domain with a plist @@ -278,7 +278,7 @@ Auth0 Check the [FAQ](FAQ.md) for more information about the alert box that pops up **by default** when using Web Auth. -> **Note** +> [!NOTE] > See also [this blog post](https://developer.okta.com/blog/2022/01/13/mobile-sso) for a detailed overview of single sign-on (SSO) on iOS. ### Next steps @@ -337,6 +337,6 @@ Please do not report security vulnerabilities on the public GitHub issue tracker

-

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

+

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

This project is licensed under the MIT license. See the LICENSE file for more info.

diff --git a/V2_MIGRATION_GUIDE.md b/V2_MIGRATION_GUIDE.md index d50da6a7..523a32b1 100644 --- a/V2_MIGRATION_GUIDE.md +++ b/V2_MIGRATION_GUIDE.md @@ -302,11 +302,37 @@ Auth0.swift now only supports the [authorization code flow with PKCE](https://au The `useUniversalLink()` method was removed as well, as Universal Links [cannot be used](https://openradar.appspot.com/51091611) for OAuth redirections without user interaction since iOS 10. -`useLegacyAuthentication()` and `useLegacyAuthentication(withStyle:)` were also removed. Auth0.swift now only uses `ASWebAuthenticationSession` to perform web-based authentication. - -> **Note** +> [!IMPORTANT] > Check the [FAQ](FAQ.md) for more information about the alert box that pops up **by default** when using Web Auth. +#### `useLegacyAuthentication()` + +`useLegacyAuthentication()` and `useLegacyAuthentication(withStyle:)` were removed. You should use `WebAuthentication.safariProvider()` instead (requires Auth0.swift [2.10+](https://github.com/auth0/Auth0.swift/releases/tag/2.1.0)). + +
+ Before / After + +```swift +// Before +Auth0 + .webAuth() + .useLegacyAuthentication() + .start { result in + // ... + } +} + +// After +Auth0 + .webAuth() + .provider(WebAuthentication.safariProvider()) + .start { result in + // ... + } +} +``` +
+ ### Credentials Manager The method `enableTouchAuth(withTitle:cancelTitle:fallbackTitle:)` was removed. You should use `enableBiometrics(withTitle:cancelTitle:fallbackTitle:evaluationPolicy:)` instead.