Authentication (B2B)

In order to provide services to your users, you must be able to identify who those users are. This process is called User Authentication. There are a number of ways to perform authentication of a user - via social media accounts, username and password, passwordless - and it’s often recommended that you go beyond a first factor for authenticating the user by enabling multi-factor authentication (MFA).

Best Practice

It’s important to consider both security and user experience when designing how you will authenticate your users. Providing for multiple primary factors, and/or enforcing more than one factor during authentication, are ways that you can provide both.

There are a number of things you will want to consider when looking at functionality and workflow:

• Where will users enter their credentials?
• How will you keep user credentials safe?
• How will you maintain your authentication system?
• How can you provide password authentication for your users?
• How can you prevent hackers from trying to log in as your users?
• How will you implement authentication in different kinds of applications?
• How can you make login easy for your users when they come from different language backgrounds?
• How will you provide a good user experience as you migrate away from any legacy authentication system?
• What should you consider when integrating applications with Auth0?
• Do you need to provide multi-factor authentication?
• What do you do if you have a service that doesn’t have a way for the user to log in ahead of time?
• Can you pass the same user access token from one API to another?
• What do you do if you need to isolate users by organization?
• How will you handle identifying which organization users belong to?
• What’s the benefit of providing enterprise connections for your organizations?

Auth0 Universal Login provides users with a safe and secure experience - no matter whether you choose to provide for user ID/password credentials sign in, or allow the so-called Bring Your Own Identity scenarios provided via Social Login. There are also brand recognition benefits to centralizing the login experience with Universal Login, even if you feel you will also have product-specific branding requirements. The Auth0 UI widgets typically used with Universal Login also provide out-of-the-box support with regards to internationalization for users with different language requirements, and out-of-the-box support for Auth0 features such as MFA and attack protection allow you to put barriers in place in order to prevent hackers attempting to access users’ accounts.

Allowing users to sign in via user ID/password credentials means that you’re not reliant on the status of third-party identity providers for your users to access your system. You also have the means to require the credentials used to align with your corporate policies. Auth0 assists with this by providing you with multiple options in support of user ID/password logins, and the guidance provided will help you understand you can leverage these options. Adding social support at some stage, as an additional primary authentication factor, gives you added flexibility and can help you better understand your users without the need to question them further by leveraging the information already stored by the various social login providers.

If you have an existing legacy identity store, you’ll also want to see User Migration. This section discusses the advantages of migrating to Auth0’s managed identity storage in terms of safety and security.

For customer facing applications, OpenID Connect (OIDC) is the most frequently used industry standard protocol, and OIDC has first-class citizen support in Auth0. Auth0 provides support for various different approaches for integrating various different applications, so you’ll want to see the section on application integration for the information you’ll need to make an informed choice.

When calling one API from another API, or from any situation where there is no authenticated user context - such as one or more cron jobs, report generators, or continuous integration/delivery systems - you will need a way to authorize the application instead of a user. This is a one step process where the application is authenticated (using a client ID and secret) and then authorized in one call. You can learn more about this in our authorization work stream under machine-to-machine (m2m) authorization.

Often companies need to segregate their users by organization and sometimes users can have access to more than one organization. Knowing which of these scenarios is relevant to your company will help define how to determine in which connection a user exists: whether you need to do it, when you need to do it, and how to accomplish it. See Home Realm Discovery to determine if this is something relevant to your company.

Universal Login

Do you have, or will you have, more than one application in your system? If the answer to this question is yes, then you will want a centralized sign in experience. To achieve a seamless Single Sign-on (SSO) experience between multiple applications, it is critical to have a centralized location to redirect your users for authentication. This allows you a way to provide your users with a consistent experience if you add social authentication in the future, add third party applications to your system, or add multi-factor authentication as an option (or requirement) for your users - and also allow you to take advantage of new features for improving your users’ experience with little, if any, added development effort.

Best Practice

If you have more than one application, the best practice is to redirect to a centralized location to authenticate the user. With Auth0, this means taking advantage of Universal Login, which provides many security and user experience benefits out-of-the-box, including SSO.

Auth0 Universal Login makes authenticating users a short, easy process which can be accomplished in three easy steps (all of our Quickstarts demonstrate this and our SDKs hide the complexity for you too):

1. Determine how and when you want to redirect from your application.
2. Set up the appropriate branding and/or customized HTML in your Auth0 configuration.
3. Set up your application to receive and handle the response from the Authorization Server.

Home realm discovery

Home realm discovery (HRD) is the process of identifying which identity provider (or which connection in Auth0) the user belongs to before authenticating them. There are two ways HRD can occur:

• Provide a way for the decision to be made at the application
• Have Home Realm Discovery happen on the Universal Login page

Your system may need to do either or both methods so it is important to understand all approaches to HRD so that you can apply the one(s) that make the most sense to your applications.

Application driven HRD

A common way of determining which realm a user belongs to is when an application is branded for each organization. As part of this, an organization will typically have its own instance of the application, typically accessed via a different URL. This copy or instance can be physically isolated (running on a separate set of servers) or virtually isolated (running on shared servers) and is generally denoted through either a custom hostname (companyA.application1.yourcompany.com) or path (application1.yourcompany.com/companyA).

Best practice

If your application already knows the specific connection (IdP) required then you can also pass that along when you redirect the user to /authorize, via use of the connection query parameter.

If this is the case for your application(s), then home realm discovery is a simple matter of storing the org_id with the organization-specific application configuration and sending that as the organization parameter when redirecting the user to Universal Login. Doing so will limit the user to that specific organization and its set of configured connections.

Best practice

If an organization needs more than one IdP, then you may have to do a second round of Home Realm Discovery (once the organization has been identified). Auth0 will typically manage this for you if you are using the Organizations Feature.

If the user is shared between multiple organizations using a single identity, you must support Home Realm Discovery on the Universal Login Page. This will allow Universal Login to identify the user first and then present the realms appropriate for that user leading to a better user experience.

Sending the organization and/or connection parameters can be achieved by adding them as a query parameter when you redirect the user to the /authorize endpoint. For more information, see the Authentication API docs. However, you will generally accomplish this using the SDK for whichever language your application is written in.

HRD through Universal Login

There are three main approaches to Home Realm Discovery:

• Discover the realm through the user’s email subdomain.
• Discover the realm by looking up a user identifier in some sort of map of an identifier to realm map.
• Allow the user to choose or enter their realm (or organization).

In both of the first two approaches, you may consider doing “Identifier First Login”. This means that you present only the ability to enter an identifier first. After which, you collect the user’s identifier, and then, based on the identifier, you either automatically redirect the user or present a way for the user to enter their password if redirection is unnecessary. Auth0 provides implementation out of the box to take care of all of this, via the use of Universal Login.

Though it is possible to implement Identifier First Login or allow a user to select their organization at the application instead of on the Universal Login Page, this can add complexity with respect to single sign on as well as complexity associated with replicating that behavior in all of your applications. Instead Auth0 recommends implementing some form of HRD through Universal Login.

HRD through Universal Login using the email subdomain

The simplest way to implement home realm discovery on the universal login page is to utilize the email subdomain of the user’s identifier to map that to their Identity Provider. This, of course, only works in situations where the email subdomain will be a 1:1 mapping to an organization or at least to an Identity Provider.

Auth0’s Lock widget or Universal Login can do this for you if you are using the domain map in an enterprise connection; however, if you want to build this yourself, you can, but it requires you to build a mapping of email subdomain to connection.

Additionally, when using the Universal Login experience, the Organizations Feature will help you in two ways:

1. If you have not passed an org_id to /authorize when you initiated the login request, Auth0 will present the user with a prompt to enter the organization they belong to.
2. If the Organization has more than one IdP associated with it, Auth0 will present the user with buttons to choose the organization or a form to enter a username and password.

HRD through Universal Login using the Identifier to Realm Map

A second, more complex alternative is to store a map of identifiers to IdP and provide a public endpoint to access that information. Then on the Universal Login page, you can find the connection and redirect back to /authorize with the connection. The main drawbacks to this approach are latency and, more importantly, security when it comes to identifier discovery: if you’re using email addresses, this makes it much easier for someone to discover whether a particular email address is a user of yours.

Best practice

Any public endpoint should have rate limiting applied to it to prevent hackers from using it to discover information and to prevent denial of service attacks.

HRD through Universal Login using user choice

The other option is to allow your users to choose from a list, if you don’t mind making public the list of organizations who use your product, or by allowing the user to enter their organization name explicitly. This would typically be done before redirecting the user to Universal Login. Once the user tells you which organization they belong to, you can redirect to Auth0 with the connection for that organization specified or have Auth0 simply prompt the user for their username and password if the connection is a database connection.

Username and password authentication

Nearly every B2C application provides the ability for its customers to create a new set of credentials. This is a common form of authentication that all users are familiar with.

Username password authentication comes in multiple flavors at Auth0. If your application is a green-field application with no existing user base, then a simple Auth0 out-of-the-box Database Connection will give you everything you need to start authenticating your users. However, if you have a legacy user store (such as your own database of users or an existing LDAP system) you have a couple of different options for migrating your users as discussed in our guidance on User migration.

However you end up provisioning the users for your database connection, the authentication of those users is quite similar. It requires you to present users with a form to enter their username and password. As mentioned in the guidance concerning Universal Login, the simplest and safest way to authenticate users with a username and password is to redirect them to a centralized login page and collect their username and password there. This allows Auth0 to determine whether they have already authenticated and skip the login form entirely when it’s not needed.

Best Practice

Collecting credentials only at the centralized login page will reduce the surface area for potential leak of user secrets. It will also reduce the need to collect credentials unnecessarily. See Universal Login for more information.

Application integration

Once you’ve figured out how you want to authenticate your users, the next step is to determine how you will initiate that authentication. Each application will typically have its own starting point.

Native mobile applications (and desktop applications) should use the system browser for authentication, or they open themselves up to additional security risks. See Native vs. Browser Login on Mobile for more information.

As discussed, we’ve found that most of our customers use OpenID Connect (OIDC) as the industry-standard protocol when it comes to their customer-facing applications. Figuring out which OIDC flow to use is your first task, and you will want to start by reviewing the our grant mapping guidance in the first instance.

If you want to allow anonymous users access to any part of our application then you need to determine if you will be redirecting right away or prompting your users to redirect only when required (or perhaps some combination of both; see Redirect Users After Login for further discussion). If users can deep link to a protected version (or area) of your site then you will need to determine the links to your application that will result in an automatic redirect to Auth0.

Anonymous access

It is important to consider the user experience when someone first comes to your application. If your application supports anonymous user access (quite common for eCommerce applications) there are different scenarios to consider:

• Are they returning to the application after having already logged in, or

• If this is the first time they are accessing the application:

  • Have they already accessed a different application that uses the same Auth0 tenant,
  • Have they ever (or perhaps not in a long time) authenticated on this device or browser.

When an anonymous user accesses your application, it can often be desirable for the application to discover if the user has already logged into a different application in the same family, or to remember this user even if the application is a SPA with no state. For example, if you can determine that the user is already logged in, you might decide to have the UI header in the application skip displaying a login button and instead have an account or profile menu for the user. To accomplish this you will want to utilize “silent authentication”. Silent authentication will allow you to check to see if the user is logged in without prompting them to log in if they are not. Then the application can present a login button if necessary. If the user is logged in already, however, then you will receive tokens and will not have to present the user with a login button again.

Checking for a login session by redirecting to Auth0 can be helpful for your application, but if this will result in a lot of requests, you should employ a throttling mechanism to avoid latency and/or rate limiting.

Calls to the Management API are subject to Auth0 Rate Limiting policy. You must take this into consideration, and to assist, Auth0 generally recommends use of the appropriate Auth0 SDK for your development environment rather than calling our APIs directly.

Deep linking to protected endpoints

There are a variety of reasons why someone might link directly to a particular page within your application that is only accessible by authenticated users. If this is possible for your application you should automatically redirect your user to Auth0 if they are not authenticated. Once they authenticate and the authorization server returns them to your application, you can redirect them to where they intended to go in the first place.

Best Practice

Most modern authentication frameworks support middleware for redirecting to an authorization server such as Auth0. When selecting one, here are some key considerations:

• Support for confidential clients, non-confidential clients, or both
• Support for configuration via discovery endpoint or explicitly inline
• Support for token validation including expirations, signatures, claims and scopes
• Support for Refresh Tokens if needed

Authenticating the user

Authentication is the process of determining user identity. The result of authentication in an OIDC context is an ID Token. This token contains information about the user and should only be able to be obtained if the user authenticates using one or more factors as defined by the authorization server (the most common form being user ID and password). There are a few things you may also need to consider in addition to obtaining an ID Token:

• Do we also need an Access Token in order to call a shared API?
• Is your application a single-page application and only requires an ID Token? See Authorization Code Grant with PKCE for more information.
• Is your application a native application (mobile or desktop) and/or do you need a Refresh Token? See Authorization Code Grant with PKCE for more information.

Before you go live, you should ensure that only the grants that you are using for each application are enabled in your configuration for your Application.

Authorization code grant (with or without PKCE)

If your SDK only supports the Authorization Code grant, or you need an Access Token or Refresh Token, then Authorization Code grant (with or without PKCE) can also be used to retrieve an ID Token. The Authorization Code grant includes an additional API call to exchange the code for a token which can result in additional unnecessary latency if all you need is the ID Token. In many cases the hybrid flow is implemented to provide optimum access to the ID Token while still leveraging Authorization Code grant workflow for the secure and safe retrieval of Access and Refresh Tokens.

While Auth0 supports the use of implicit grant for browser-based applications requiring only an ID Token, it is recommended to use authorization code grant with PKCE. For detailed information, see OAuth2 Implicit Grant and SPA on the Auth0 Blog.

If you need a Refresh Token so that you can obtain a new Access Token or ID Token without having to re-authenticate the user, then you must use the authorization code grant.

Attack protection

The reason that authentication systems are important is to prevent bad actors from accessing applications and user data that they should not. We want to place as many barriers as possible between those bad actors and access to our systems. One of the easiest ways to do this is to ensure that your attack protection with Auth0 is configured correctly, so take a moment to read the guidance on this subject and ensure that it’s working correctly for you.

Best Practice

Anomaly detection is handled behind the scenes by Auth0 and provides a great security feature for your product. If you’re going to utilize it, ensure that you have set up your Email Provider and configured your Email Templates before turning on email delivery to your users.

SSO with legacy systems

In a large scale re-structure it’s not always possible—or practical—to update all your applications at once. In fact, our recommended best practice is to plan for an iterative-style approach when it comes to integrating with Auth0. If your applications already participate in Single Sign-on (SSO), and your legacy identity system supports protocols such as OIDC or SAML, then you have a couple of options available if you want to continue to provide SSO as you integrate with Auth0:

• Update your existing identity provider in your legacy SSO system to redirect to Auth0 for login (e.g., using SAML), or
• Have Auth0 redirect to your legacy SSO system to login. This requires configuring your legacy system as an IdP in Auth0 (i.e., either using SAML or OIDC).

Best Practice

Supporting an SSO experience with your legacy system can add complexity, but may be worth it to generate a more seamless user experience as you integrate with Auth0. If you intend to go down this path, planning for it early can help ensure that it is possible to achieve. If you don’t already have SSO at a centralized service, then the complexity to add it will unlikely be worth the benefits.

This is a complex topic that will likely need some additional investigation depending on your current legacy architecture, and we recommend you only look into this if you currently have SSO support in your legacy system. Note: if you are currently redirecting from your applications to a centralized system to authenticate your users and that system only asks for credentials if you don’t already have a session with the centralized system, then you have a legacy SSO implementation.

Enterprise Login

The “bring your own identity” scenario has become a must-have for almost all B2B applications. Most enterprise companies expect to be able to integrate their IdP into your application so their employees don’t need to store another set of credentials. This is a valuable way of simplifying the user authentication experience without compromising security, and using Universal Login makes it easy to start adding support for Enterprise Connections with minimal disruption.

Best Practice

Once you start supporting enterprise connections for users, you must do some form of Home Realm Discovery so that you can determine which connection to send the user to for authentication.

With enterprise connection support, user identities and credentials are managed by the identity provider of your customers’ organization, as well as certain identity claims - which Auth0 will use to populate the user profile.

Best Practice

“Bring your own identity” is a great feature to provide, but if you don’t support this from day one, and sometimes even if you do, you may have an organization that wants to switch to their own IdP after already having used the application for a while. You will need a way to link user accounts to provide an effective way of associating the new identity with the old database identity.

Multi-factor authentication (MFA)

In an era where misuse of user credentials is at an all-time high, protecting your systems when it’s so common for hackers to steal users identity information in general is a challenge. One of the most effective ways though is to provide users with the ability to configure a second factor for protecting their account. More commonly referred to as Multi-Factor Authentication. This will ensure that only a valid user can access their account, even if they use a username and password that may have been compromised from a different application.

Best Practice

It’s quite common for customer facing applications to provide users with an option for adding a second factor rather than forcing them to use a second factor. For more information regarding this, see providing your users with an option to add MFA.

Auth0 supports a number of different options when it comes to enabling MFA for protecting user account access, and there are several practices to ensure that you will truly be providing a flexible second factor barrier to access:

• Auth0 Guardian: a service that provides both Push notification generation and an application for allowing or denying requests. Push sends notification to a user’s pre-registered device - typically a mobile or tablet - from which a user can immediately allow or deny account access via the simple press of a button.
• Time-based One-Time Password (TOTP): allows you to register a device - such as Google Authenticator - that will generate a one-time password which changes over time and which can be entered as the second factor to validate a user’s account.
• SMS: for sending a one-time code over SMS which the user is then prompted to enter before they can finish authenticating.
• Voice: for delivering a one-time code through a phone call which the user is then prompted to enter before they can finish authenticating.
• Duo: allows you to use your Duo account for multi-factor authentication.
• Email: allows you to use your email account for multi-factor authentication.

Whilst MFA workflow using technologies such as Guardian or Google Authenticator is typically provided via a separate application that runs on a mobile or tablet device, if you don’t want your customers to have to download a separate application Auth0 also provides you with an SDK that you can use to build second factor workflow right in your existing mobile device application(s).

Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

B2B IAM Project Planning Guide

Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers’ organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

Multiple Organization Architecture