diff --git a/main/config/navigation/en.json b/main/config/navigation/en.json index 0d8600ff8a..9b4351f5bb 100644 --- a/main/config/navigation/en.json +++ b/main/config/navigation/en.json @@ -834,8 +834,7 @@ "pages": [ "docs/authenticate/database-connections/passkeys/configure-passkey-policy", "docs/authenticate/database-connections/passkeys/monitor-passkey-events-in-tenant-logs", - "docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications", - "docs/authenticate/database-connections/passkeys/native-passkeys-api" + "docs/authenticate/database-connections/passkeys/passkey-apis" ] }, "docs/authenticate/database-connections/password-options", diff --git a/main/config/redirects.json b/main/config/redirects.json index b5d63ab47e..1cfd900a7e 100644 --- a/main/config/redirects.json +++ b/main/config/redirects.json @@ -69,11 +69,11 @@ }, { "source": "/docs/native-passkeys-api", - "destination": "/docs/authenticate/database-connections/passkeys/native-passkeys-api" + "destination": "/docs/authenticate/database-connections/passkeys/passkey-apis" }, { "source": "/docs/native-passkeys-for-mobile-applications", - "destination": "/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications" + "destination": "/docs/authenticate/database-connections/passkeys/passkey-apis" }, { "source": "/docs/articles", diff --git a/main/docs/api/myaccount.mdx b/main/docs/api/myaccount.mdx index 7422b5c614..d2b4dfa168 100644 --- a/main/docs/api/myaccount.mdx +++ b/main/docs/api/myaccount.mdx @@ -5,13 +5,6 @@ description: "Documentation for Auth0's My Account API" Version: 1.0 (Current) - -

Limited Early Access

- -The My Account API is available in Limited Early Access. To request access, contact your Auth0 account manager. To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages). - - - The Auth0 My Account API provides a dedicated set of endpoints for users to manage their own account information. Customers can use these APIs to build self-service experiences in their applications or progressively add details to a user account. The My Account API operates within the context of the currently logged-in user and can be used directly within user-facing applications. @@ -79,7 +72,7 @@ If you're using Universal Login, read the following articles: If you're using embedded login, read the following articles: - [Call Your API Using Resource Owner Password Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow) -- [Login Flow with Native Passkeys API](https://auth0.com/docs/native-passkeys-api#login-flow) +- [Login Flow with Passkey APIs](https://auth0.com/docs/authenticate/database-connections/passkeys/passkey-apis#login-flow) ## Examples @@ -121,10 +114,6 @@ curl --request POST \ --data '{ "grant_type": "urn:okta:params:oauth:grant-type:webauthn", "client_id": "{yourClientId}", "scope": "create:me:authentication_methods offline_access", "audience": "https://{yourDomain}/me/" "auth_session": "{sessionIdFromTheFirstRequest}", "authn_response": "{authenticatorResponse}"}' ``` -## Rate limits - -During Early Access, the My Account API is limited at a tenant level to 25 requests per second. - ### Authentication diff --git a/main/docs/authenticate/database-connections/passkeys.mdx b/main/docs/authenticate/database-connections/passkeys.mdx index d81321d65f..57690d4274 100644 --- a/main/docs/authenticate/database-connections/passkeys.mdx +++ b/main/docs/authenticate/database-connections/passkeys.mdx @@ -25,7 +25,7 @@ Auth0 supports passkeys as an authentication method for database connections wit * Universal Login passkeys for web-based applications * [Embedded Login native applications](/docs/authenticate/passwordless/implement-login/embedded-login/native) -* [Native passkeys for Android and iOS applications](/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications) +* [Passkey APIs for native mobile and web applications](/docs/authenticate/database-connections/passkeys/passkey-apis) Auth0 has a limit of 20 passkeys per user. diff --git a/main/docs/authenticate/database-connections/passkeys/native-passkeys-api.mdx b/main/docs/authenticate/database-connections/passkeys/native-passkeys-api.mdx deleted file mode 100644 index fc736c70ba..0000000000 --- a/main/docs/authenticate/database-connections/passkeys/native-passkeys-api.mdx +++ /dev/null @@ -1,423 +0,0 @@ ---- -description: Auth0 Authentication API specs for Native Passkeys -title: Native Passkeys API ---- -import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx" - - - -Passkeys are a phishing-resistant alternative to traditional forms of authentication (such as username and password) that offer an easier and more secure user experience. For complete implementation details, review [Native Passkeys for Mobile Applications](/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications). - -Native passkeys use a combination of Auth0 and native iOS or Android APIs to embed challenge flows directly into your mobile application. The endpoints listed below are a subset of the Auth0 Authentication API. To learn more about using this API, review the [Authentication API Introduction](https://auth0.com/docs/api/authentication#introduction). - -Passkeys have three related flows: - -* **Signup**: Creates a new user account with a passkey as the primary authentication method. -* **Enrollment**: Adds a passkey as an authentication method to an existing user's account. -* **Login**: Challenges an existing user to authenticate using a passkey associated with their account. - -## Signup Flow - -### Request Signup Challenge - -`POST /passkey/register` - -Initiates the passkey signup flow for a new user. - -In response, Auth0 returns [PublicKeyCredentialCreationOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions) and a session ID. Check `timeout` under `authn_params_public_key` in response for session timeout. - -The passkey signup flow supports Organizations through the `organization` parameter, following the behavior described in [Login Flows for Organizations](/docs/manage-users/organizations/login-flows-for-organizations). If your application is configured for **Business Users**, you must provide the `organization` parameter and a valid Organization name or identifier value. After the user registers a passkey, Auth0 enrolls them in the provided Organization. - -#### Request Parameters - -| Parameter | Description | -| --- | --- | -| `client_id` | **Required**. The `client_id` of your application. | -| `realm` | **Optional**. The name of the connection to associate with this user.

If a connection is not specified, your tenant's default directory is used. | -| `user_profile` | **Required**. An object containing identification information for the user. By default, this includes a valid `email` and an optional display `name`.

If you have enabled [Flexible Identifiers](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers) for your database connection, you may use a combination of `email`, `phone_number`, or `username` as identifiers. These options can be required or optional and must match your Flexible Identifier configuration.

If the passed identifier (such as `email`) already exists in the directory, the user should be prompted to complete the Login flow instead. | - -#### Code Samples - -##### Request - -```text lines -POST /passkey/register -Content-Type: application/json - -{ - "client_id": "{YOUR_CLIENT_ID}", - "realm": "{OPTIONAL_CONNECTION}", - "user_profile": { - "email": "{VALID_EMAIL_ADDRESS}", - "name": "{OPTIONAL_USER_DISPLAY_NAME}", - } -} -``` - -##### Response - -```json lines expandable -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "authn_params_public_key": { - "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}", - "timeout": {MILLISECONDS}, - "rp": { - "id": "{THE_CUSTOM_DOMAIN}", - "name": "{THE_CUSTOM_DOMAIN}" - }, - "pubKeyCredParams": [ - { "type": "public-key", "alg": -8 }, - { type: 'public-key', alg: -7 }, - { type: 'public-key', alg: -257 } - ], - "authenticatorSelection": { - "residentKey": "required", - "userVerification": "preferred" - }, - "user": { - "id": "{GENERATED_ID}", - "name": "{USER-ENTERED_IDENTIFIER}", - "displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}" - } - }, - "auth_session": "{SESSION_ID}" -} -``` - -#### Remarks - -* After the challenge request is complete, your application can continue the user registration process using native [Android](https://developer.android.com/identity/passkeys/create-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) APIs. -* You must then [authenticate the new user](#authenticate-new-user) using information retrieved through the native APIs to complete the flow. - -### Authenticate New User - - -Native Passkey registration is not currently supported when SMS/Email OTP verification is required on the same connection during signup. - - -`POST /oauth/token` - -Uses the Token endpoint to authenticate the user with the provided credentials to create their account and return the requested tokens. - -The `authn_response` parameter is based on the [Web Authentication API specification](https://www.w3.org/TR/webauthn-3/). In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs: - -* [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys) -* [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) - -#### Request Parameters - -| Parameter | Description | -| --- | --- | -| `grant_type` | **Required**. Include the value: `urn:okta:params:oauth:grant-type:webauthn` | -| `client_id` | **Required**. The `client_id` of your application | -| `realm` | **Optional**. The name of the connection to associate with the user. If a connection is not specified, your tenant's default directory is used. | -| `scope` | **Optional**. Use `openid` to get an ID token or `openid profile email` to include user profile information in the ID token. | -| `audience` | **Optional**. API identifier of the API for which you want to get an access token. | -| `auth_session` | **Required**. Session ID returned during the initial passkey challenge request. | -| `authn_response` | **Required**. An object containing the following items: | -| `authn_response.id` | **Required**. Base64URL credential ID. | -| `authn_response.rawId` | **Required**. Base64URL credential ID. | -| `authn_response.type` | **Required**. Include the value: `public-key` | -| `authn_response.authenticatorAttachment` | **Required**. Include the values: | -| `authn_response.response` | **Required**. An object containing the following items: | - -#### Code Samples - -##### Request - -```text lines -POST /oauth/token -Content-Type: application/json - -{ - "grant_type": "urn:okta:params:oauth:grant-type:webauthn", - "client_id": "{YOUR_CLIENT_ID}", - "realm": "{OPTIONAL_CONNECTION}", - "scope": "{OPTIONAL_REQUESTED_SCOPE}", - "audience": "{OPTIONAL_REQUESTED_AUDIENCE}" - "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}", - "authn_response": { - "id": "{BASE64URL_ID}", - "rawId": "{BASE64URL_RAWID}", - "type": "public-key", - "authenticatorAttachment": "platform|cross-platform", - "response": { - "clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}", - "attestationObject": "{BASE64URL_ATTESTATION_OBJECT}", - {OTHER_PROPERTIES} - }, - } -} -``` - -##### Response - -```json lines -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "access_token": "{BASE64_TOKEN}", - "refresh_token": "{BASE64_TOKEN}", - "id_token": "{BASE64_TOKEN}", - "token_type": "Bearer", - "expires_in": {SECONDS} -} -``` - -## Enrollment Flow - -Enrolling a new passkey for a user involves a two-step process using the My Account API. This flow ensures that the passkey enrollment is initiated securely and then verified. - -Before initiating the enrollment flow, ensure you have an access token with the `create:me:authentication_methods` scope for the `/me` endpoint. - -### Initiate Passkey Enrollment - -`POST /me/v1/authentication-methods` - -The first step is to initiate the enrollment process. This is done by making a POST request to the `/me/v1/authentication-methods` endpoint. - -#### Request Parameters - -| Parameter | Description | -| --- | --- | -| `type` | **Required**. Include the value: `public-key`. | -| `connection` | **Optional**. The name of the connection in which to create the passkey. | -| `identity` | **Optional**. The user's identity. Used with linked accounts. | - -#### Code Samples - -##### Request - -```json lines -{ - "type": "passkey", - "connection": "CONNECTION_NAME", - "identity": "IDENTITY_USER_ID" -} -``` - -##### Response - -```json lines -{ - "authn_params_public_key": { - "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION", - "timeout": MILLISECONDS, - "rp": { - "id": "CUSTOM_DOMAIN", - "name": "CUSTOM_DOMAIN" - }, - "pubKeyCredParams": [ - { type: 'public-key', alg: -8 }, - { type: 'public-key', alg: -7 }, - { type: 'public-key', alg: -257 } - ], - "authenticatorSelection": { - "residentKey": "required", - "userVerification": "preferred" - }, - "user": { - "id": "GENERATED_ID", - "name": "USER_ENTERED_IDENTIFIER", - "displayName": "USER_ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING" - } - }, - "auth_session": "SESSION_ID" -} -``` - -#### Remarks - -* The `auth_session` property in the response body is the identifier of the current authentication session. This must be passed to the `/verify` endpoint. -* After the challenge request is complete, your application can continue the user enrollment process using native [Android](https://developer.android.com/identity/passkeys/create-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) APIs. This will prompt the user to create a passkey with their authenticator (such as fingerprint scanner, security key, or phone). - -### Verify Passkey Enrollment - -`POST /me/v1/authentication-methods/passkey|new/verify` - - - -The ID in the path is always `passkey|new` for new enrollments. - - - -Once the user has successfully created the passkey with their authenticator, the client application will receive an `AuthenticatorAttestationResponse` from the WebAuthn API. This response needs to be sent back to the Auth0 service to complete and verify the enrollment. - -* [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys) -* [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) - -#### Request Parameters - -| Parameters | Description | -| --- | --- | -| `auth_session` | **Required**. The session identifier received in the response of the first POST request to `/me/v1/authentication-methods`. | -| `authn_response` | **Required**. The `authn_response` parameter is based on the Web Authentication API specification. In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs. | -| `authn_response.id` | **Required**. Base64URL credential ID. | -| `authn_response.rawId` | **Required**. Base64URL credential ID. | -| `authn_response.type` | **Required**. Include the value: `public-key`. | -| `authn_response.authenticatorAttachment` | **Required**. Include the values: `platform`, `cross-platform`. | -| `authn_response.response` | **Required**. An object containing the following items: | - -#### Code Samples - -##### Request - -```json lines -{ - "auth_session": "SESSION_ID", - "authn_response": { - "id": "BASE64URL_ID", - "rawId": "BASE64URL_RAWID", - "type": "public-key", - "authenticatorAttachment": "platform|cross-platform", - "response": { - "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON", - "attestationObject": "BASE64URL_ATTESTATION_OBJECT" - } - } -} -``` - -#### Remarks - -Once this step is completed successfully, the passkey is enrolled for the user and can be used for future authentications. - -## Login Flow - -### Request Login Challenge - -`POST /passkey/challenge` - -Initiates the passkey login flow for an existing user who saved a passkey to their account during their initial signup. - -In response, Auth0 returns [PublicKeyCredentialRequestOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrequestoptions), a session ID, and a Relying Party identifier `rpId`. Check `timeout` under `authn_params_public_key` in response for session timeout. The `rpId` returned in the response is the identifier the native device (iOS/Android) uses to look up saved credentials bound to a domain. For a passkey created on a web application (e.g., `example.com`) to be available in the native flow, the `rpId` returned must match the web's `rpId`. To learn how to customize the RPID for your tenant, read [Configure Passkey Policy](/docs/authenticate/database-connections/passkeys/configure-passkey-policy#configure-relying-party-id-rpid). - -The passkey login flow supports Organizations through the `organization` parameter, following the behavior described in [Login Flows for Organizations](/docs/manage-users/organizations/login-flows-for-organizations). If your application is configured for **Business Users**, you must provide the `organization` parameter and a valid Organization name or identifier value. - -All issued tokens are in the context of the provided Organization. If you enabled [Auto-Membership](/docs/manage-users/organizations/login-flows-for-organizations#auto-membership) for your Organization, the user is automatically enrolled in the Organization after successfully authenticating. - -#### Request Parameters - -| Parameter | Description | -| --- | --- | -| `client_id` | **Required**. The `client_id` of your application. | -| `realm` | **Optional**. The name of the connection to associate with the user.

If a connection is not specified, your tenant's default directory is used. | - -#### Code Samples - -##### Request - -```text lines -POST /passkey/challenge -Content-Type: application/json - -{ - "client_id": "{YOUR_CLIENT_ID}", - "realm": "{OPTIONAL_CONNECTION}" -} -``` - -##### Response - -```json lines -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "authn_params_public_key": { - "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}", - "timeout": {AUTH_TIMEOUT_IN_MILLISECONDS}, - "rpId": "{CUSTOM_DOMAIN}", - "userVerification": "preferred" - }, - "auth_session": "{SESSION_ID}" -} -``` - -#### Remarks - -* After the challenge request is complete, your application can continue the login process using native [Android](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account) APIs. -* You must then [authenticate the existing user](#authenticate-existing-user) using information retrieved through the native APIs to complete the flow. - -### Authenticate Existing User - -`POST /oauth/token` - -Uses the Token endpoint to authenticate the user with the provided credentials and return the requested tokens. - -The `authn_response` parameter is based on the [Web Authentication API specification](https://www.w3.org/TR/webauthn-3/). In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs: - -* [Android login documentation](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) -* [iOS login documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account) - -#### Request Parameters - -| Parameter | Description | -| --- | --- | -| `grant_type` | **Required**. Include the value: `urn:okta:params:oauth:grant-type:webauthn` | -| `client_id` | **Required**. The `client_id` of your application | -| `realm` | **Optional**. The name of the connection to associate with the user. If a connection is not specified, your tenant's default directory is used. | -| `scope` | **Optional**. Use `openid` to get an ID token or `openid profile email` to include user profile information in the ID token. | -| `audience` | **Optional**. API identifier of the API for which you want to get an access token. | -| `auth_session` | **Required**. Session ID returned during the initial passkey challenge request. | -| `authn_response` | **Required**. An object containing the following items: | -| `authn_response.id` | **Required**. Base64URL credential ID. | -| `authn_response.rawId` | **Required**. Base64URL credential ID. | -| `authn_response.type` | **Required**. Include the value: `public-key` | -| `authn_response.authenticatorAttachment` | **Optional**. Include the values: | -| `authn_response.response` | **Required**. An object containing the following items: | -| `authn_response.clientExtensionResults` | **Optional**. Contains results of processing client extensions requested by the relying party. | - -#### Code Samples - -##### Request - -```text lines -POST /oauth/token -Content-Type: application/json - -{ - "grant_type": "urn:okta:params:oauth:grant-type:webauthn", - "client_id": "{YOUR_CLIENT_ID}", - "realm": "{OPTIONAL_CONNECTION}", - "scope": "{OPTIONAL_REQUESTED_SCOPE}", - "audience": "{OPTIONAL_REQUESTED_AUDIENCE}" - "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}", - "authn_response": { - "id": "{BASE64URL_ID}", - "rawId": "{BASE64URL_RAWID}", - "type": "public-key", - "authenticatorAttachment": "platform|cross-platform", - "response": { - "authenticatorData": "{BASE64URL_AUTHENTICATORDATA}", - "clientDataJSON": "{BASE64URL_CLIENTDATAJSON}", - "signature": "{BASE64URL_SIGNATURE}", - "userHandle": "{BASE64URL_USERHANDLE}" - }, - "clientExtensionResults": {OPTIONAL_OBJECT} - }, -} -``` - -##### Response - -```json lines -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "access_token": "{BASE64_TOKEN}", - "refresh_token": "{BASE64_TOKEN}", - "id_token": "{BASE64_TOKEN}", - "token_type": "Bearer", - "expires_in": {SECONDS} -} -``` diff --git a/main/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications.mdx b/main/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications.mdx deleted file mode 100644 index 7fd32fd7a6..0000000000 --- a/main/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications.mdx +++ /dev/null @@ -1,301 +0,0 @@ ---- -description: Learn how to implement native passkey flows for Android and iOS applications -title: Native Passkeys for Mobile Applications ---- -import { ReleaseStageNotice } from "/snippets/ReleaseStageNotice.jsx" - - - -Passkeys are a phishing-resistant alternative to traditional forms of authentication (such as username and password) that offer an easier and more secure user experience. They are modeled from FIDO® W3C Web Authentication (WebAuthn) and Client to Authenticator Protocol (CTAP) [specifications](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#intro). - -Auth0 currently supports passkeys as an authentication method for database connections and offers two methods of implementation: - -* [Universal Login passkeys](/docs/authenticate/database-connections/passkeys) for web-based applications. -* Native passkeys for Android and iOS applications. -* [Embedded Login for web-based and native applications](/docs/authenticate/passwordless/implement-login/embedded-login) - -## How it works - -Native passkeys use a combination of the [Auth0 Authentication API](/docs/authenticate/database-connections/passkeys/native-passkeys-api) and native iOS or Android APIs to embed challenge flows directly into your mobile application. This allows you to create an integrated signup and login experience for your application that does not rely on redirecting users through their browsers to complete authentication. - -The following example demonstrates what a new user may experience during the passkey signup flow: - -1. A new user launches your mobile application and accesses the login screen. Since they are a new user, they select the Sign Up button. -2. On the next screen, the user enters their email address and selects Create Account. -3. Next, the user is asked if they want to create a passkey for your application. To proceed, the user selects Continue. -4. To generate a passkey, the user must locally authenticate on their device using biometrics or another authentication method, such as entering a PIN. -5. After local authentication is complete, a new passkey is saved to the user’s device and synced with their passkey provider, such as iCloud or Google. -6. After the passkey is saved, the user continues your new user registration process to finalize their account. - -Once this process is complete, the user can authenticate with their saved passkey the next time they log in to your application. - -## Before you begin - -### Configure a custom domain - -Native passkeys require the use of a custom domain. Before proceeding, ensure you have configured a custom domain for your tenant. To learn more, review [Custom Domains](/docs/customize/custom-domains). - -### Configure your passkey policy - -Before you can implement native passkeys for Android or iOS applications, you must configure a passkey policy in your Auth0 tenant. To prepare your tenant, follow the steps in [Configure Passkey Policy](/docs/authenticate/database-connections/passkeys/configure-passkey-policy). - -### Prepare your application - -To prepare your application for native passkeys, you must configure your Device Settings and add the `Passkey` grant. You can complete these configurations through your Auth0 Dashboard or the Management API. - -#### Associated domains - -For end users to authenticate with a single passkey with across different application types or application types with different subdomains, set the Relying Party ID to the root or parent domain. To learn more, read [Passkeys](/docs/authenticate/database-connections/passkeys). - -### Configure Auth0 Dashboard - -1. Navigate to [Applications > Applications](https://manage.auth0.com/#/applications) and select the application you wish to update. -2. At the bottom of the Settings tab, select **Advanced Settings**. Then, choose the **Device Settings** tab. -3. Complete the **iOS** and **Android** sections as needed for your application. Then, click **Save Changes**. -4. In the Advanced Settings section, select the **Grant Types** tab. -5. Enable the **Passkey** grant, then select **Save Changes**. - -#### Management API - -Call the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint and: - -* Update `grant_types` to include `urn:okta:params:oauth:grant-type:webauthn`. -* Use the `mobile` object to specify iOS and Android device settings as needed. - -## Implement passkey flows - -You can define the following passkey flows for your application: - -* [Signup flow](#signup-flow): Allows new users to generate and save a passkey during the user registration process. -* [Login flow](#login-flow): Allows an existing user who has already enrolled in passkeys to authenticate with their saved passkey during the login process. - -### Signup flow - -A user initiates the passkey signup flow when they first attempt to log in to your application. - -If the user provides an identifier that already exists, it’s recommended that you prompt the user to complete the login flow instead. Otherwise, the action will fail. - -#### Flow steps - -1. A user visits your application and chooses to register a new account. The user provides an identifier requested by your application, such as their email address. -2. Your application then initiates the signup challenge by calling the [Request Signup Challenge](/docs/authenticate/database-connections/passkeys/native-passkeys-api#request-signup-challenge) endpoint of the Auth0 Authentication API: - - - * If you do not specify a `realm`, your tenant’s default directory is used. - * By default, email is the required identifier. If you have enabled [Flexible Identifiers](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers) for your database connection, you may use a combination of `email`, `phone_number`, or `username` instead. These options can be required or optional and must match your Flexible Identifier configuration. - - - ```text lines - POST /passkey/register - Content-Type: application/json - - { - "client_id": "{YOUR_CLIENT_ID}", - "realm": "{OPTIONAL_CONNECTION}", - "user_profile": { - "email": "{VALID_EMAIL_ADDRESS}", - "name": "{OPTIONAL_USER_DISPLAY_NAME}", - } - } - ``` - -3. In response, Auth0 returns [`PublicKeyCredentialCreationOptions`](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions) along with an `auth_session` ID and `rpId` as `rp.id`: - - ```text lines expandable - HTTP/1.1 200 OK - Content-Type: application/json - - { - "authn_params_public_key": { - "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}", - "timeout": {MILLISECONDS}, - "rp": { - "id": "{YOUR_CUSTOM_DOMAIN}", - "name": "{YOUR_CUSTOM_DOMAIN}" - }, - "pubKeyCredParams": [ - { type: 'public-key', alg: -8 }, - { type: 'public-key', alg: -7 }, - { type: 'public-key', alg: -257 } - ], - "authenticatorSelection": { - "residentKey": "required", - "userVerification": "preferred" - }, - "user": { - "id": "{GENERATED_ID}", - "name": "{USER-ENTERED_IDENTIFIER}", - "displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}" - } - }, - "auth_session": "{SESSION_ID}" - } - ``` - - The returned `rpId` in the response matches the domain used in the webflow for passkeys to work in associated domains. - - -4. Your application then completes the user registration process using the appropriate native APIs: - - * Review [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys). - * Review [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service). -5. Your application then uses the credential information obtained through the registration process, including `authn_response` details, to call the [Token](/docs/authenticate/database-connections/passkeys/native-passkeys-api#authenticate-new-user) endpoint: - - ```text lines - POST /oauth/token - Content-Type: application/json - - { - "grant_type": "urn:okta:params:oauth:grant-type:webauthn", - "client_id": "{YOUR_CLIENT_ID}", - "realm": "{OPTIONAL_CONNECTION}", - "scope": "{OPTIONAL_REQUESTED_SCOPE}", - "audience": "{OPTIONAL_REQUESTED_AUDIENCE}" - "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}", - "authn_response": { - "id": "{BASE64URL_ID}", - "rawId": "{BASE64URL_RAWID}", - "type": "public-key", - "authenticatorAttachment": "platform|cross-platform", - "response": { - "clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}", - "attestationObject": "{BASE64URL_ATTESTATION_OBJECT}", - {OTHER_PROPERTIES} - }, - }, - } - ``` - - -6. Auth0 creates a new user account and returns the requested tokens to complete the flow: - - ```text lines - HTTP/1.1 200 OK - Content-Type: application/json - - { - "access_token": "{BASE64_TOKEN}", - "refresh_token": "{BASE64_TOKEN}", - "id_token": "{BASE64_TOKEN}", - "token_type": "Bearer", - "expires_in": {SECONDS} - } - ``` - -### Login flow - -An existing user initiates the passkey login flow when they attempt to log in to your application. This flow only applies to existing users who have saved passkeys to their accounts during initial signup. - -#### Flow Steps - -1. A user launches your application and begins the login process. Your application then initiates the login challenge by calling the [Request Login Challenge](/docs/authenticate/database-connections/passkeys/native-passkeys-api#request-login-challenge) endpoint of the Authentication API: - - - - If you do not specify a `realm`, your tenant’s default directory is used. - - - - ```text lines - POST /passkey/challenge - Content-Type: application/json - - { - "client_id": "{YOUR_CLIENT_ID}", - "realm": "{OPTIONAL_CONNECTION}" - } - ``` - - -2. In response, Auth0 returns [`PublicKeyCredentialRequestOptions`](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrequestoptions) along with an `auth_session` to continue the flow in your application: - - ```text lines - HTTP/1.1 200 OK - Content-Type: application/json - - { - "authn_params_public_key": { - "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}", - "timeout": {AUTH_TIMEOUT_IN_MILLISECONDS}, - "rpId": "{CUSTOM_DOMAIN}", - "userVerification": "preferred" - }, - "auth_session": "{SESSION_ID}" - } - ``` - -3. Your application then completes the login process using the appropriate native APIs: - - * Review [Android login documentation](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) - * Review [iOS login documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account). -4. Your application then uses the credential information obtained through the login process, including `authn_response` details, to call the [Token](/docs/authenticate/database-connections/passkeys/native-passkeys-api#authenticate-existing-user) endpoint: - - ```text lines - POST /oauth/token - Content-Type: application/json - - { - "grant_type": "urn:okta:params:oauth:grant-type:webauthn", - "client_id": "{YOUR_CLIENT_ID}", - "realm": "{OPTIONAL_CONNECTION}", - "scope": "{OPTIONAL_REQUESTED_SCOPE}", - "audience": "{OPTIONAL_REQUESTED_AUDIENCE}" - "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}", - "authn_response": { - "id": "{BASE64URL_ID}", - "rawId": "{BASE64URL_RAWID}", - "type": "public-key", - "authenticatorAttachment": "platform|cross-platform", - "response": { - "authenticatorData": "{BASE64URL_AUTHENTICATORDATA}", - "clientDataJSON": "{BASE64URL_CLIENTDATAJSON}", - "signature": "{BASE64URL_SIGNATURE}", - "userHandle": "{BASE64URL_USERHANDLE}" - }, - "clientExtensionResults": {OPTIONAL_OBJECT} - } - } - ``` - - - - - -5. Auth0 authenticates the credentials and returns the requested tokens to complete the flow: - - ```text lines - HTTP/1.1 200 OK - Content-Type: application/json - - { - "access_token": "{BASE64_TOKEN}", - "refresh_token": "{BASE64_TOKEN}", - "id_token": "{BASE64_TOKEN}", - "token_type": "Bearer", - "expires_in": {SECONDS} - } - ``` - - -## References - -The following resources can be referenced when implementing native passkeys for your mobile application: - -* Auth0 Authentication API - - + [Request signup challenge](/docs/authenticate/database-connections/passkeys/native-passkeys-api#request-signup-challenge) - + [Authenticate new user](/docs/authenticate/database-connections/passkeys/native-passkeys-api#authenticate-new-user) - + [Request login challenge](/docs/authenticate/database-connections/passkeys/native-passkeys-api#request-login-challenge) - + [Authenticate existing user](/docs/authenticate/database-connections/passkeys/native-passkeys-api#authenticate-existing-user) -* Android resources - - + [Registration documentation](https://developer.android.com/identity/passkeys/create-passkeys) - + [Login documentation](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) -* iOS resources - - + [Registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) - + [Login documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account) diff --git a/main/docs/authenticate/database-connections/passkeys/passkey-apis.mdx b/main/docs/authenticate/database-connections/passkeys/passkey-apis.mdx new file mode 100644 index 0000000000..677361018d --- /dev/null +++ b/main/docs/authenticate/database-connections/passkeys/passkey-apis.mdx @@ -0,0 +1,498 @@ +--- +title: "Passkey APIs for Embedded Applications" +description: "Build native and web embedded passkey authentication using Auth0's Passkey APIs." +--- + +Passkeys are a phishing-resistant alternative to traditional forms of authentication (such as username and password) that offer an easier and more secure user experience. They are modeled from FIDO® W3C Web Authentication (WebAuthn) and Client to Authenticator Protocol (CTAP) [specifications](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#intro). + +Auth0 currently supports passkeys as an authentication method for database connections with two methods of implementation: + +* [Universal Login passkeys](/docs/authenticate/database-connections/passkeys) for web-based applications. +* Passkey APIs for native mobile applications (iOS, Android) and web applications. +* [Embedded Login for web-based and native applications](/docs/authenticate/passwordless/implement-login/embedded-login) + +## How it works + +The Passkey APIs use a combination of the Auth0 Authentication API and platform-specific credential APIs to embed challenge flows directly into your application. For native mobile apps, this means using iOS or Android platform APIs. For web applications, this means using the WebAuthn browser API. This allows you to create an integrated signup and login experience that does not rely on redirecting users through their browsers to complete authentication. + +The following example demonstrates what a new user may experience during the passkey signup flow: + +1. A new user launches your mobile application and accesses the login screen. Since they are a new user, they select the Sign Up button. +2. On the next screen, the user enters their email address and selects Create Account. +3. Next, the user is asked if they want to create a passkey for your application. To proceed, the user selects Continue. +4. To generate a passkey, the user must locally authenticate on their device using biometrics or another authentication method, such as entering a PIN. +5. After local authentication is complete, a new passkey is saved to the user's device and synced with their passkey provider, such as iCloud Keychain or Google Password Manager. +6. After the passkey is saved, the user continues your new user registration process to finalize their account. + +Once this process is complete, the user can authenticate with their saved passkey the next time they log in to your application. + +## Before you begin + +### Configure a custom domain + +Native passkeys require the use of a custom domain. Before proceeding, ensure you have configured a custom domain for your tenant. To learn more, review [Custom Domains](/docs/customize/custom-domains). + +### Configure your passkey policy + +Before you can implement native passkeys for Android or iOS applications, you must configure a passkey policy in your Auth0 tenant. To prepare your tenant, follow the steps in [Configure Passkey Policy](/docs/authenticate/database-connections/passkeys/configure-passkey-policy). + +### Prepare your application + +All applications using the Passkey APIs must add the `Passkey` grant and configure their Relying Party ID. Depending on your platform, you may also need to configure additional settings through your Auth0 Dashboard or the Management API. + + + +**Configure Device Settings in Auth0 Dashboard:** +1. Navigate to [Applications > Applications](https://manage.auth0.com/#/applications) and select your application. +2. At the bottom of the Settings tab, select **Advanced Settings**, then choose the **Device Settings** tab. +3. In the **iOS** section, enter your: + - Team ID + - Bundle ID +4. Click **Save Changes**. + +**Apple App Site Association file:** +Auth0 automatically hosts the `apple-app-site-association` file on your tenant's custom domain at `https://YOUR_CUSTOM_DOMAIN/.well-known/apple-app-site-association` based on the Team ID and Bundle ID you configure. You do not need to host this file yourself. + +**Configure Associated Domains entitlement:** +In Xcode, enable the Associated Domains entitlement and add an entry for your custom domain (format: `webcredentials:YOUR_CUSTOM_DOMAIN`). + + +**Configure Device Settings in Auth0 Dashboard:** +1. Navigate to [Applications > Applications](https://manage.auth0.com/#/applications) and select your application. +2. At the bottom of the Settings tab, select **Advanced Settings**, then choose the **Device Settings** tab. +3. In the **Android** section, enter your: + - Package name + - SHA-256 fingerprint (of your app's signing certificate) +4. Click **Save Changes**. + +**Digital Asset Links file:** +Auth0 automatically hosts the `assetlinks.json` file on your tenant's custom domain at `https://YOUR_CUSTOM_DOMAIN/.well-known/assetlinks.json` based on the package name and SHA-256 fingerprint you configure. You do not need to host this file yourself. + + +**Configure Allowed Web Origins:** +1. Navigate to [Applications > Applications](https://manage.auth0.com/#/applications) and select your application. +2. In the Settings tab, scroll to **Allowed Web Origins**. +3. Add your web application's origin (e.g., `https://YOUR_CUSTOM_DOMAIN`). +4. Click **Save Changes**. + +**No app association files needed for web applications.** Web apps use the WebAuthn browser API, which handles origin validation automatically. + +**Ensure rpId matches your origin:** The rpId returned by Auth0 must match your web app's origin for the WebAuthn flow to succeed. + + + +**Add the Passkey grant (all platforms):** +1. In the Advanced Settings section, select the **Grant Types** tab. +2. Enable the **Passkey** grant, then select **Save Changes**. + +Alternatively, use the Management API: +Call the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint and: +* Update `grant_types` to include `urn:okta:params:oauth:grant-type:webauthn`. +* For native apps, use the `mobile` object to specify iOS and Android device settings as needed. + +#### Relying Party ID (rpId) + +For end users to authenticate with a single passkey across different application types or application types with different subdomains, set the Relying Party ID to the root or parent domain. To learn more, read [Passkeys](/docs/authenticate/database-connections/passkeys). + +## Implement passkey flows + +You can define the following passkey flows for your application: + +* [Signup flow](#signup-flow): Allows new users to generate and save a passkey during the user registration process. +* [Login flow](#login-flow): Allows an existing user who has already enrolled in passkeys to authenticate with their saved passkey during the login process. +* [Enrollment flow](#enrollment-flow): Allows existing users to add a passkey to their account after authentication. + +### Signup flow + +A user initiates the passkey signup flow when they first attempt to log in to your application. + +If the user provides an identifier that already exists, it's recommended that you prompt the user to complete the login flow instead. Otherwise, the action will fail. + +#### Step 1: Request signup challenge + +Your application initiates the signup challenge by calling the `POST /passkey/register` endpoint: + +```text lines +POST /passkey/register +Content-Type: application/json + +{ + "client_id": "YOUR_CLIENT_ID", + "realm": "OPTIONAL_CONNECTION", + "user_profile": { + "email": "user@example.com", + "name": "John Doe" + } +} +``` + + +* If you do not specify a `realm`, your tenant's default directory is used. +* By default, email is the required identifier. If you have enabled [Flexible Identifiers](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers) for your database connection, you may use a combination of `email`, `phone_number`, or `username` instead. + + +Auth0 returns `PublicKeyCredentialCreationOptions` along with an `auth_session` ID: + +```json lines +{ + "authn_params_public_key": { + "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION", + "timeout": 60000, + "rp": { + "id": "YOUR_CUSTOM_DOMAIN", + "name": "YOUR_CUSTOM_DOMAIN" + }, + "pubKeyCredParams": [ + { "type": "public-key", "alg": -8 }, + { "type": "public-key", "alg": -7 }, + { "type": "public-key", "alg": -257 } + ], + "authenticatorSelection": { + "residentKey": "required", + "userVerification": "preferred" + }, + "user": { + "id": "GENERATED_ID", + "name": "USER_EMAIL", + "displayName": "USER_EMAIL_OR_NAME" + } + }, + "auth_session": "SESSION_ID" +} +``` + +#### Step 2: Create passkey on device + +Your application uses the returned `PublicKeyCredentialCreationOptions` to create a passkey on the user's device. The method depends on your platform: + + + +Use `ASAuthorizationPlatformPublicKeyCredentialProvider` to create the credential with Face ID, Touch ID, or device PIN. + +Review [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service). + + +Use `CredentialManager` to create the credential with biometric or device PIN authentication. + +Review [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys). + + +Use `navigator.credentials.create()` with the `PublicKeyCredentialCreationOptions` returned from Auth0. + +Review [MDN Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API). + + + +#### Step 3: Exchange credentials for tokens + +Your application uses the credential information from the registration process to call the `POST /oauth/token` endpoint: + +```text lines +POST /oauth/token +Content-Type: application/json + +{ + "grant_type": "urn:okta:params:oauth:grant-type:webauthn", + "client_id": "YOUR_CLIENT_ID", + "realm": "OPTIONAL_CONNECTION", + "scope": "openid profile email", + "audience": "YOUR_API_IDENTIFIER", + "auth_session": "SESSION_ID_FROM_STEP_1", + "authn_response": { + "id": "BASE64URL_ID", + "rawId": "BASE64URL_RAWID", + "type": "public-key", + "authenticatorAttachment": "platform", + "response": { + "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON", + "attestationObject": "BASE64URL_ATTESTATION_OBJECT" + } + } +} +``` + +Auth0 creates a new user account and returns the requested tokens: + +```json lines +{ + "access_token": "eyJz93a...TJVA95w", + "refresh_token": "GEz...NaYM", + "id_token": "eyJ0exA...f1jrv3", + "token_type": "Bearer", + "expires_in": 86400 +} +``` + + +Native Passkey registration is not currently supported when SMS/Email OTP verification is required on the same connection during signup. + + +For exhaustive parameter documentation, see the [Authentication API explorer](/api/authentication). + +### Login flow + +An existing user initiates the passkey login flow when they attempt to log in to your application. This flow only applies to existing users who have saved passkeys to their accounts during initial signup. + +#### Step 1: Request login challenge + +Your application initiates the login challenge by calling the `POST /passkey/challenge` endpoint: + +```text lines +POST /passkey/challenge +Content-Type: application/json + +{ + "client_id": "YOUR_CLIENT_ID", + "realm": "OPTIONAL_CONNECTION" +} +``` + + +If you do not specify a `realm`, your tenant's default directory is used. + + +Auth0 returns `PublicKeyCredentialRequestOptions` along with an `auth_session`: + +```json lines +{ + "authn_params_public_key": { + "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION", + "timeout": 60000, + "rpId": "YOUR_CUSTOM_DOMAIN", + "userVerification": "preferred" + }, + "auth_session": "SESSION_ID" +} +``` + +#### Step 2: Retrieve passkey from device + +Your application uses the returned `PublicKeyCredentialRequestOptions` to retrieve a passkey from the user's device. The method depends on your platform: + + + +Use `ASAuthorizationPlatformPublicKeyCredentialProvider` to retrieve the credential with Face ID, Touch ID, or device PIN. + +Review [iOS login documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account). + + +Use `CredentialManager` to retrieve the credential with biometric or device PIN authentication. + +Review [Android login documentation](https://developer.android.com/identity/passkeys/sign-in-with-passkeys). + + +Use `navigator.credentials.get()` with the `PublicKeyCredentialRequestOptions` returned from Auth0. + +Review [MDN Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API). + + + +#### Step 3: Exchange credentials for tokens + +Your application uses the credential information from the login process to call the `POST /oauth/token` endpoint: + +```text lines +POST /oauth/token +Content-Type: application/json + +{ + "grant_type": "urn:okta:params:oauth:grant-type:webauthn", + "client_id": "YOUR_CLIENT_ID", + "realm": "OPTIONAL_CONNECTION", + "scope": "openid profile email", + "audience": "YOUR_API_IDENTIFIER", + "auth_session": "SESSION_ID_FROM_STEP_1", + "authn_response": { + "id": "BASE64URL_ID", + "rawId": "BASE64URL_RAWID", + "type": "public-key", + "authenticatorAttachment": "platform", + "response": { + "authenticatorData": "BASE64URL_AUTHENTICATORDATA", + "clientDataJSON": "BASE64URL_CLIENTDATAJSON", + "signature": "BASE64URL_SIGNATURE", + "userHandle": "BASE64URL_USERHANDLE" + }, + "clientExtensionResults": {} + } +} +``` + +Auth0 authenticates the credentials and returns the requested tokens: + +```json lines +{ + "access_token": "eyJz93a...TJVA95w", + "refresh_token": "GEz...NaYM", + "id_token": "eyJ0exA...f1jrv3", + "token_type": "Bearer", + "expires_in": 86400 +} +``` + +For exhaustive parameter documentation, see the [Authentication API explorer](/api/authentication). + +### Enrollment flow + +Enrolling a new passkey for an existing, authenticated user uses the My Account API. This flow is useful when you want to allow users to add a passkey to their account after they've already authenticated with another method—for example, during onboarding or from a settings page. + +#### Prerequisites + +Before initiating the enrollment flow, ensure you have: + +1. An access token with the `create:me:authentication_methods` scope for the `/me` endpoint. +2. Activated the My Account API for your tenant. + +For complete setup instructions, see [My Account API](/docs/manage-users/my-account-api). + +#### Step 1: Initiate passkey enrollment + +Your authenticated application calls the `POST /me/v1/authentication-methods` endpoint with the access token: + +```text lines +POST /me/v1/authentication-methods +Authorization: Bearer YOUR_ACCESS_TOKEN +Content-Type: application/json + +{ + "type": "passkey", + "connection": "CONNECTION_NAME" +} +``` + +Auth0 returns a challenge and session ID: + +```json lines +{ + "authn_params_public_key": { + "challenge": "GENERATED_CHALLENGE", + "timeout": 60000, + "rp": { + "id": "YOUR_CUSTOM_DOMAIN", + "name": "YOUR_CUSTOM_DOMAIN" + }, + "pubKeyCredParams": [ + { "type": "public-key", "alg": -8 }, + { "type": "public-key", "alg": -7 }, + { "type": "public-key", "alg": -257 } + ], + "authenticatorSelection": { + "residentKey": "required", + "userVerification": "preferred" + }, + "user": { + "id": "GENERATED_ID", + "name": "USER_IDENTIFIER", + "displayName": "USER_DISPLAY_NAME" + } + }, + "auth_session": "SESSION_ID" +} +``` + +#### Step 2: Create passkey on device + +Your application uses the returned `PublicKeyCredentialCreationOptions` to create a passkey on the user's device, following the same platform-specific steps as the signup flow: + + + +Use `ASAuthorizationPlatformPublicKeyCredentialProvider` to create the credential with Face ID, Touch ID, or device PIN. + +Review [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service). + + +Use `CredentialManager` to create the credential with biometric or device PIN authentication. + +Review [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys). + + +Use `navigator.credentials.create()` with the `PublicKeyCredentialCreationOptions` returned from Auth0. + +Review [MDN Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API). + + + +#### Step 3: Verify passkey enrollment + +Once the user has created the passkey with their authenticator, call the `POST /me/v1/authentication-methods/passkey|new/verify` endpoint to complete the enrollment: + +```text lines +POST /me/v1/authentication-methods/passkey|new/verify +Authorization: Bearer YOUR_ACCESS_TOKEN +Content-Type: application/json + +{ + "auth_session": "SESSION_ID_FROM_STEP_1", + "authn_response": { + "id": "BASE64URL_ID", + "rawId": "BASE64URL_RAWID", + "type": "public-key", + "authenticatorAttachment": "platform", + "response": { + "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON", + "attestationObject": "BASE64URL_ATTESTATION_OBJECT" + } + } +} +``` + +Once this step completes successfully, the passkey is enrolled for the user and can be used for future authentications. + +For exhaustive parameter documentation and an interactive try-it-out, see the [My Account API explorer](/api/myaccount). + +## Using passkeys across native and web + +A passkey created in one of your applications can be used to sign in to your other applications — including across native and web — when those applications share the same Relying Party ID (rpId). This works because passkey providers (iCloud Keychain, Google Password Manager, 1Password, Dashlane, and others) sync credentials across the user's devices within the same provider. + +### How users move between platforms + +In most cases, users do not need to scan a QR code or use a second device. The flow depends on whether the passkey is already available on the device they're using: + +- **Same provider, different device** (most common): A user enrolls a passkey on your iOS app; their iCloud Keychain syncs it to their Mac, where they can sign in to your web app immediately. Same applies to Android passkeys synced via Google Password Manager to Chrome on a Chromebook or Windows PC signed into the same Google account. +- **Cross-ecosystem or shared device** (less common): If the passkey isn't available on the device the user is on (for example, an iPhone passkey being used on a Windows PC, or a public computer), the browser offers a QR code to authenticate via the user's phone using [hybrid transport (CTAP 2.2)](https://fidoalliance.org/specs/fido-v2.2-rd-20230321/fido-client-to-authenticator-protocol-v2.2-rd-20230321.html). The user keeps their passkey on their phone; the QR code only bridges the two devices for that one sign-in. + +### Choose your Relying Party ID carefully + +The rpId determines which origins can use a passkey. Auth0 sets the rpId to your custom domain by default. Choose the rpId that best matches the scope across which you want passkeys to work — and no broader. + +**Recommended:** Use a parent domain that scopes to your authentication and product surfaces, such as `auth.example.com` or `accounts.example.com`. A passkey created with `rpId=auth.example.com` works on `auth.example.com` and any subdomain of it (for example, `app.auth.example.com`, `m.auth.example.com`). + +**Avoid using your eTLD+1 (registrable apex) as the rpId** — for example, `example.com`. Setting the rpId at this level lets every subdomain of `example.com` request and use those passkeys, including marketing sites, third-party-hosted services, or domains operated by other teams. This expands the trust boundary far beyond your authentication surface. + +For deeper guidance, refer to: + +- [Passkeys.dev — Server-side: Relying Party ID](https://passkeys.dev/docs/advanced/server/) for rpId selection trade-offs +- [Web.dev — Choosing the Relying Party ID](https://web.dev/articles/webauthn-rp-id) for browser-side considerations +- [FIDO Alliance — User experience guidelines for passkeys](https://fidoalliance.org/ux-guidelines-passkeys/) for user-facing design patterns + +### Multi-domain and brand scenarios + +If you serve multiple brand domains (e.g., `login.brand1.com` and `login.brand2.com`), passkeys do not automatically work across them — each domain has its own rpId. See [Passkeys with Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains/passkeys) for guidance on per-domain enrollment, communication, and migration patterns. + +### Configuration checklist + +Once you've chosen an rpId, ensure all your applications share it: + +1. **Use one custom domain** as the rpId across every native and web application that should share passkeys. +2. **Native apps**: configure Device Settings in the Auth0 Dashboard with your iOS Team ID/Bundle ID and Android package name/SHA-256 fingerprint. Auth0 hosts the `apple-app-site-association` and `assetlinks.json` files on your custom domain automatically. +3. **Web apps**: serve your web origin from the rpId or a subdomain of it, and add it to **Allowed Web Origins** for CORS. + +## References + +The following resources can be referenced when implementing passkey authentication for your application: + +* **Auth0 APIs** + + [Authentication API explorer](/api/authentication) — Passkey authentication endpoints + + [My Account API explorer](/api/myaccount) — Passkey enrollment endpoints + + [My Account API guide](/docs/manage-users/my-account-api) — Activation, scopes, and CORS + +* **Platform Documentation** + + [Apple Developer: Supporting passkeys](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys) + + [Android Developers: Create passkeys](https://developer.android.com/identity/passkeys/create-passkeys) + + [Android Developers: Sign in with passkeys](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) + + [MDN Web Authentication API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) + + [WebAuthn specification](https://www.w3.org/TR/webauthn-3/) + +* **Additional Resources** + + [passkeys.dev](https://passkeys.dev) — Comprehensive passkey implementation guide + + [FIDO Alliance UX Guidelines](https://fidoalliance.org/ux-guidelines-passkeys/) — User experience best practices diff --git a/main/docs/authenticate/login/embedded-login.mdx b/main/docs/authenticate/login/embedded-login.mdx index 953fd8df96..0fa5009a21 100644 --- a/main/docs/authenticate/login/embedded-login.mdx +++ b/main/docs/authenticate/login/embedded-login.mdx @@ -12,6 +12,10 @@ Auth0 supports Embedded Login with - -The My Account API is available in Early Access. To request access, contact your Auth0 account manager or contact [Auth0 Support](https://support.auth0.com). To learn more about Auth0's product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). - - - The Auth0 My Account API provides a dedicated set of endpoints for users to manage their own account information. Customers can use these APIs to build self-service experiences in their applications or progressively add details to a user account. The My Account API operates within the context of the currently logged-in user and can be used directly within user-facing applications. @@ -61,12 +55,6 @@ To learn more about how to manage application API access policies and their asso ## Default Policy setting - - -Authentication Assurance for the **My Account API** is currently in Early Access with a single-option policy. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the program, contact [Auth0 Support](https://support.auth0.com). - - - The Default Policy provides built-in authentication assurance for the My Account API by requiring [Step-up Authentication](/docs/secure/multi-factor-authentication/step-up-authentication). When enabled, Auth0 automatically enforces that users have authenticated recently and with a second factor. The policy enforces 2FA within 15 minutes. Auth0 applies this rule at login and on every Refresh Token exchange: @@ -76,7 +64,7 @@ The policy enforces 2FA within 15 minutes. Auth0 applies this rule at login and -The Default Policy is not compatible with Classic Login. Enable this feature if your tenant uses Universal Login or a supported embedded flow ([Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) or [native passkeys](/docs/authenticate/database-connections/passkeys/native-passkeys-api)). +The Default Policy is not compatible with Classic Login. Enable this feature if your tenant uses Universal Login or a supported embedded flow. @@ -84,10 +72,10 @@ The Default Policy is not compatible with Classic Login. Enable this feature if To enable the Default Policy for the My Account API: -1. Navigate to [**Applications > APIs**](https://manage.auth0.com/#/apis), then select the **My Account API**. -2. Select the **Settings** tab. -3. Under **Default Policy**, toggle on **Require 2FA**. -4. Select **Save**. +1. Navigate to [**Applications > APIs**](https://manage.auth0.com/#/apis), then select the **My Account API**. +2. Select the **Settings** tab. +3. Under **Default Policy**, toggle on **Require 2FA**. +4. Select **Save**. When your tenant has the Default Policy enabled, it is automatically attached whenever a new My Account API is created. @@ -146,7 +134,7 @@ If you’re using