Single Identity Provider: Authorization

When thinking about authorization, you typically need to consider how you determine what a person is allowed to do and how you communicate this information to your applications and/or APIs. Depending on the applications you have, you may be affected by one or both of these. In our architecture scenarios, we provide general purpose guidance on B2B Authorization, which we recommend reviewing alongside the guidance provided here.

• ID Tokens are often used to convey user authorization information to applications through custom claims, which can be added using Rules extensibility. Added claims can allow you to present a user interface in which users don’t have the ability to attempt something they are not permitted to do. Authorization information in an ID Token also provides any application backend with a way to restrict users from bypassing frontend controls for traditional web apps.

Best Practice

You can leverage Auth0 Role-Based Access Control (RBAC) via the Auth0 Authorization Core feature to define access permissions, which can be automatically applied to Access Tokens. For further details, see Enable Role-Based Access Control for APIs.

Auth0 RBAC functionality can also provide information that you can add as custom claims to identity tokens (and access tokens, if you prefer manual application). Auth0 Organizations can leverage Auth0 RBAC capability via one or more membership-assigned roles. To learn more, see Add Roles to Organization Members.

• APIs that provide public-facing access to shared resource services are typically protected via access control mechanisms. For this purpose, Auth0 provides the ability to create an authorization bearer token, or OAuth 2 access token, which can convey user authorization information to an API, typically by using Auth0 Role-Based Access Control (RBAC) to apply one or more membership-assigned roles or by adding custom claims via Rules extensibility. You can also leverage Auth0 RBAC capability to automatically adjust the scope claim of an access token. APIs can then use this information to apply the appropriate level of access control, which allows your API to enforce policy rules without having to do an extra lookup to get information about the user.
• In certain cases, you may want to implement application-level policies at the Auth0 Tenant; this allows you to apply policies to a whole range of applications and resource services (APIs) without needing to modify each one independently. You typically implement this via Rules extensibility.

Best Practice

Auth0 Organizations provides Auth0 Rules with access to organization-centric information that can be accessed when authenticating a user. This information is available via the organization object contained within the Rules context object. The organization object also provides access to any metadata provisioned against an Organization definition in Auth0. To learn more, see Custom Development for Organizations.

ID token claims

Usually claims can be added to identity tokens as discussed in our ID Token Claims best practice guidance. When using the Auth0 Organizations feature, an org_id claim is automatically added to any identity token (for an example, see Work with Tokens and Organizations) issued for users with organization membership. This parameter is validated by Auth0 SDKs. You can also add supplemental information associated with an Auth0 Organization by adding a custom claim to the identity token:

context.idToken['http://travel0.net/multifactor'] = context.multifactor;

Note: If you have configured your tenant to support organization names in the Authentication API, the org_name claim is automatically included in ID tokens. To learn more, review Use Organization Names in Authentication API.

SAML assertion

While the Auth0 Organization feature does not support SAML-aware applications, a SAML assertion generated by an upstream Identity Provider (IdP) can be configured to populate standard or custom claims in an identity token consumed downstream. For example, you could define the mappings section of a SAML enterprise connection:

{ 
  "user_id": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ],
  "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
  "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
  "given_name": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ], 
  "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
  "groups": "http://schemas.xmlsoap.org/claims/Group"
}

In this example, each field will be assigned a value in the user object in a Rule, which will either map to standard claims in an identity token or can be mapped using custom claims. To learn more about customizing SAML mappings, see Connect Your App to SAML Identity Providers: Set up mappings.

Access token claims

In addition to any other claims you are adding to your access token for access control decisions (see our general Access Token Claims best practice guidance), you will typically want to communicate the organization to which the user belongs.

As with the identity token, when using the Auth0 Organizations feature, the org_id claim is automatically added to any access token (for an example, see Work with Tokens and Organizations) issued for users with organization membership. You can also add supplemental information associated with an Auth0 Organization by adding a custom claim to the access token:

context.accessToken['http://travel0.net/multifactor'] = context.multifactor;

Note: If you have configured your tenant to support organization names in the Authentication API, the org_name claim is automatically included in access tokens. To learn more, review Use Organization Names in Authentication API.

Alternatively, you could create a unique API audience for each organization, which would result in a unique API definition in Auth0. While this mechanism can mitigate the need for employing custom Rule extensibility, the complexity it introduces can be challenging. A simple comparison is as follows:

Approach	Pros	Cons
Unique API Audience	* Out-of-the-box support for machine-to-machine access for a single organization. * Audience is a standard claim in an access token. * Refresh token processing requires no additional organization logic.	* Must automate the creation of an API for every organization. * Independent roles may need to be created if using RBAC. Must automate the provisioning of Roles to Membership.* API implementation has to process for multiple audiences.
Custom Claim	Simplifies Auth0 Tenant configuration.	Custom code needed in a rule to add the organization to the access token.

Roles

The Auth0 Organizations feature also supports Role-Based Access Control (RBAC) via the Authorization Core feature associated with an Auth0 Tenant. RBAC is applied at the Auth0 Organization membership level.

You can enable Auth0 Authorization Core RBAC for an API, which will result in the default scope claim in access tokens being modified automatically and a permission claim being added by default (for an example, see Work with Tokens and Organizations). You can also add role information to identity tokens as custom claims by accessing the authorization object available in the Rules context object. To learn more, see Rules with Authorization Sample Use Cases: Add User Roles to Tokens.

Access control

Resource-level policy enforcement is the responsibility of the applications and/or APIs in your system. If you attempt to enforce policies in a centralized Authorization Server, such as your Auth0 Tenant, you will quickly run into a complex control system that is difficult to maintain and understand. Instead, your centralized Authorization Server can ensure that the appropriate information about a user is included in the tokens, so that your applications and APIs have the necessary information to make policy enforcement decisions. At the very least, in situations where there is too much information to contain in a single token (for example, resource-level permissions) or where information changes frequently enough that it would be out of date if accessed directly in the token, your applications and APIs should be able to look up the correct information.

Some high-level policy enforcement, on the other hand, can be handled in a centralized fashion. For example, when using an Auth0 Tenant context, there are some situations in which you could implement a Rule that mitigates the need for every application and/or API to apply the same restrictions. These include:

• blocking access to users from a particular IP address
• implementing specific requirements around Contextual or Adaptive MFA
• restricting login to only users who have verified their email address
• restricting access to a certain API audience, so a user cannot obtain an access token for any other API audience or cannot obtain an access token for that audience under certain circumstances. In this case, if you’re creating a custom API Audience for each organization, your Rule must also ensure that the authenticating user belongs to the organization that matches the corresponding API audience.

Auth0 Management API access is not restricted by organization; access to the Auth0 Management API is made via an access token allocated for use within a machine-to-machine context and cannot be constrained by an Auth0 Organization. Therefore, do not provide your customers with direct access to your instance of the Auth0 Management API. If your customers must manage aspects of their organization, such as user accounts (see Profile Management), then you should build your own independent application and/or API for this purpose.