Change authentication experiences

Passkey Complete supports both hosted and embedded authentication experiences. Migration between these two options is straightforward and can be done with minimal downtime.

Prerequisites

An existing Passkey Complete application in the Passage Console.

Migration guides

Follow the applicable guide below to minimize disruption and ensure a smooth transition:

Migrate from embedded to hosted authentication

Update user interfaces

Remove Passage Elements used for authentication: <passage-auth>, <passage-login>, and <passage-register>. WebAuthn, passkeys and all authentication methods will be fully functional in the embedded login page.

In place of the Passage Elements, add a link or button to your hosted login page.

Toggle the switch in Passage Console

  1. Log in to the Passage Console (opens in a new tab).
  2. Navigate to your application settings.
  3. Locate the option to switch from embedded to hosted authentication.
  4. Configure the new hosted page settings.
  5. Save the changes.

Important Considerations

Passkeys Functionality: Note that passkeys are domain-bound, so users will need to create new passkeys for the hosted login page. Existing passkeys from the embedded domain will not transfer automatically.

Learn more about hosted login configuration and settings. If you encounter any issues or have questions during the migration process, don't hesitate to reach out to our support team at support@passage.id.

Migrate from hosted to embedded authentication

Create an embedded login page

Add a Passage Element to your frontend. In your web app, add the following code wherever you want your users to register or login:

<passage-auth app-id="PASSAGE_APP_ID"></passage-auth>
<script src="https://cdn.passage.id/passage-elements/v2.x/passage-elements.js"></script>

Replace PASSAGE_APP_ID with your Passage Application ID.

Prepare for downtime

Update your login buttons/links to display a message about the temporary unavailability of authentication. This step is crucial because the hosted login page will no longer be accessible after the switch.

Example message: "We're updating our authentication system. Login will be temporarily unavailable for a short period. Please check back in a few minutes."

Toggle the switch in Passage Console

  1. Log in to the Passage Console (opens in a new tab).
  2. Navigate to your application settings.
  3. Locate the option to switch from hosted to embedded authentication.
  4. Update the settings with your new embedded page details.
  5. Save the changes.

Update login buttons

WebAuthn, passkeys and all authentication methods will be fully functional in the embedded login page.

Remove the user-facing warnings and update your login buttons/links to direct users to the new embedded login page.

Important Considerations

  • Brief Authentication Downtime: The transition from hosted to embedded authentication requires a short period where authentication services will be unavailable. To minimize impact, consider scheduling this migration during a time of low user activity.
  • User Communication: During the transition, update all login interfaces with clear messages about the temporary unavailability of authentication services. This helps prevent user confusion and reduces attempts to access inactive authentication endpoints.
  • Passkeys Functionality: After the migration, passkeys will function normally alongside other authentication methods. Note that passkeys are domain-bound, so users will need to create new passkeys for the embedded login page. Existing passkeys from the hosted domain will not transfer automatically.

If you encounter any issues or have questions during the migration process, don't hesitate to reach out to our support team at support@passage.id.