Configure Single Sign-on for Auth0 Dashboard: Migrate Tenant Members

Problem statement

Enterprise subscribers can configure Auth0 to allow Tenant Members to use their own Enterprise identity provider (IdP) to authenticate to the Auth0 Dashboard through single sign-on (SSO).

This process requires the admins to work with Auth0 Support, exchanging configuration data to establish the connection.

Once the SSO connection is created, the Tenant Members should migrate their accounts to the new SSO login method (using their Identity provider).

The migration process has two variants depending on whether Home Realm Discovery (HRD) is enabled for the connection.

Cause

When creating an SSO integration with an enterprise identity provider, this will add an alternative login method to members.
By default, users can authenticate to the Public Cloud Dashboard using any available social identities (LinkedIn, Microsoft Account, GitHub, or Google) or create their own email/password identity.

Since every authentication method constitutes different identities and, consequently, different Dashboard users, the SSO identities are yet another user identity that needs to be invited to every tenant to access the Manage Dashboard for them.

The migration process essentially consists of re-inviting the tenant members with their new SSO identities to the tenants.

Solution

How to migrate before turning on Home Realm Discovery

Before turning on Home Realm Discovery, the only way to use the new SSO authentication method is to use this special URL: https://manage.auth0.com/login?connection=the_assigned_connection_name

The general flow will be:

  1. Have an existing administrator create a new invitation URL.
  2. The recipient of the invitation should first login with the new authentication method by using the URL provided by support:

https://manage.auth0.com/login?connection=the_assigned_connection_name, preferably from an incognito window or a browser different from the usual.

Remember that if this is the first time the user is authenticating with the new method, they might see a profiling step (auth0.com /profile in the address bar):

image

  1. If the above or similar screen appears, check Yes, Coding and I need advanced settings and click Next to move to the next screen.
  2. Now, the user will see a “Create a new tenant” screen. Don’t create one.

image

  1. Paste the invitation URL received in the email into the same browser where the invitation recipient just authenticated with the new SSO identity.
  2. After confirming the invitation, the new identity is now an administrator of the tenant.

How to migrate after turning on Home Realm Discovery

Once Home Realm Discovery is turned on, make it easier for users to log in with their new SSO identity when accepting the invitation. The downside is that those who still need to log in with an email/password identity will need to know the special login URL to bypass HRD.

The overall process is:

  1. Log in with an identity that is already an administrator of the tenant. If this an email/password identity that has the email domain already associated with HRD, use the following URL to force an authentication with email/password: https://manage.auth0.com/login?connection=auth0
  2. Create an invitation for the new member.
  3. If the recipient of the invitation was previously logged in with an old identity, they should log out of the dashboard.
  4. Now, the recipient can click on the invite URL. Since they logged out before, they will need to log in again.
  5. When typing the email address of an associated domain, they will see that the password field disappears, and clicking on the login button takes them to the enterprise identity provider.

NOTE: The steps for Private Cloud SSO connections are the same, but support will provide the URLs to trigger the SSO login and bypass HRD since these are specific to each private instance.

Video

Related References

1 Like