How to implement the Client Credentials Grant
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, scopespasswordless - and it's often recommended that you go beyond a first factor for authenticating the user by enabling multi-factor authentication (MFA).
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 anomaly detection 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 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 workstream 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.
Get Started with Auth0 Videos
Watch these two short videos Authenticate: How It Works and Authenticate: SPA Example to learn about the differences between authentication, authorization, and access control. Understand when and why you might use each type of authentication method: first factors, second factors, and multi-factor. Learn about the OpenID Connect (OIDC) authentication protocol. See an example using the Auth0 Quickstart for a single-page application (SPA) implementation.
Ask for a token
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 JSON Web Token (JWT)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.
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):
Modify scopes and claims
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.
If you don’t need to know ahead of time (for example, all of your users are in a shared user pool), then you don’t need to do HRD. You can allow users to authenticate first and then determine which organization they belong to using app metadata. HRD is really only needed if you have multiple connections within your Auth0 tenant.
Verify the token
Application driven HRD
A common and effective way for determining which realm a user belongs to is when an application is branded for each organization. The organization has its own instance of the application. This copy or instance can be physically isolated (running on a separate set of servers) or virtually isolated (running on shared servers, but presented as if it could be isolated), and is generally denoted through either a custom hostname (companyA.application1.yourcompany.com) or path (application1.yourcompany.com/companyA).
If your application already knows what connection (IdP) the user needs, then pass that along when you redirect the user to /authorize using the connection query parameter.
If this is the case for your application(s) then home realm discovery is a simple matter of storing the Auth0 connection name with the organization specific application configuration and sending that connection name as a parameter when redirecting the user for Universal Login. Sending the connection parameter can be achieved by adding it as a query parameter when you redirect them 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.
If an organization needs more than one IdP, then you will have to do a second round of Home Realm Discovery once identifying their organization. This can be achieved with Auth0 through creating a dedicated Auth0 tenant for that organization and creating an enterprise connection to that tenant.
HRD through Universal Login
There are three main approaches to Home Realm Discovery through Universal Login:
- Discover the realm through the user’s email subdomain.
- Discover the realm by looking up a user identifier in some sort of map of 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.
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 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.
HRD through Universal Login using the Identifier to Realm Map
A second, more complex alternative is to store a map of identifier’s 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.
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 simple 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. Once the user tells you which organization they belong to, you can redirect back to Auth0 with the connection for that organization specified, or simply prompt them for their username and password if the connection is a database connection.
Username and password authentication
Nearly every B2C application provides the ability for their 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.
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.
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.
As discussed, we've found that most of our customers use scopesOpenID 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.
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.
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.
Most modern authentication frameworks support middleware for redirecting to an authorization server such as Auth0. Ensure yours:
- Is configurable
- Can check expirations
- Supports Refresh Tokens (for confidential clients)
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 Implicit Grant 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.
If all your application needs is the ID Token and the application is browser-based, then you can always use the implicit grant to get your ID Token. This is a simple authentication flow and should be supported by your SDK (depending on the language you are developing in).
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.
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 anomaly detection 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.
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.
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.
"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 (a.k.a. Account Linking) 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 his/her account, even if they use a username and password that may have been compromised from a different application.
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.
- 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 devce 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.