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.

• 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.

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.

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.

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:

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.

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.