Getting started with authorization

As a first step to make authorization work, you must define what exactly (resources and/or roles) you want to authorize users upon. These must be registered in Multitenant Access Control accordingly.

Resource registration

Multitenant Access Control offers bulk API endpoints to register, modify and delete both static and dynamic resources. Check out our API documentation for further details.

For static resources, those endpoints can be used either by deployment scripts or the application itself, depending on the deployment setup, specifically around granting access for service-to-service communication. Dynamic resources, being created at runtime, are typically created by the application itself via API.

Keep in mind that any organization can define custom organization (tenant) roles that are granted privileges on your resources when changing or reorganizing your registered resources.

Communicate your privileges

Currently, there is no standardized or automated way for applications to define and propagate which roles they offer to other applications or which they require from other applications.

Role registration

Applications can define roles that ease granting, providing and sharing access to typical use-cases of them. Application roles group privileges on an application’s static resources in a non-disjunctive, useful way. Application functionalities can only be shared with other organizations via contracts containing these application roles.

Multitenant Access Control offers bulk API endpoints to register, modify and delete application roles including their privileges on static resources. All endpoints are idempotent, meaning that a set of roles can be registered or deleted as often as wanted, the outcome will always be the same.

See the API documentation for more information.

Access Control List

The ACL contains a list of all resources currently registered in Multitenant Access Control. Every resource is identified by id, type, owning organization and application. For every resource there is a list of the roles that can access it. The kind of access is defined by a privilege. The application compares those roles with the roles of the calling subject (user or application) to decide whether the access is granted.

See the API documentation for more information.

Evaluate access to resources

In order to decide whether access to a resource is granted, the Access Control List (ACL) has to be compared with the subject’s roles. It does not matter if the subject is a user or application.

Get the subject’s roles

The subject’s roles are required to determine resource access privileges of the subject.

Frontend

The OpenID Connect Userinfo endpoint can be queried by the frontend to gain knowledge about the user’s roles.

Backend

Multitenant Access Control offers its user a customized OAuth 2.0 Token Introspection endpoint. It verifies if a token is valid and additionally includes the OpenID Connect Userinfo response. For active tokens, the response thus also contains the subject’s roles.

Alternatively, the standard OpenID Connect Introspect and OpenID Connect Userinfo endpoints are available as well to validate the token and get the subject’s roles. See our section on OpenID Connect for details on them.

Authorization decision

If you want to authorize a subject on a small number of specific resources (e.g. one), look up in the ACL, which roles are granted the required privilege(s) (read, write, …) for that resource. Compare the resulting list of roles with the subject’s roles and grant access to the requested action if at least one match is found.

If you want to authorize a subject on a larger number of specific resources at once, start with filtering the ACL by the subject’s roles, which provides you with a set of all resources and their privileges the subject has access to. Now compare this list with the resources you could provide and grant access to the ones where the lists match.

Step-by-step summary

Upon incoming request

Extract the token from the request:
1. If using cookies, check all cookies with the expected name for the authorization cookies
  1. If there isn’t any valid cookie:
    
    For requests to html pages either redirect user to log in or offer the user a possibility to trigger log-in in the UI.
    
    For requests to API endpoints: return HTTP status code 401 Unauthorized.
2. If there is an Authorization header, use the token provided after the prefix "Bearer ".
As the token is opaque, validate it using the OAuth 2.0 Token Introspect endpoint (see also RFC 7662 section 2.2).
1. Our customized Introspect endpoint will also return the subject’s roles in the response for active tokens.
2. The result should be cached for some seconds using a hash derived from the token as key to avoid having to repeat the introspection on each incoming request. This is a tradeoff as invalidated tokens or changed role assignments of the subject won’t have an immediate effect anymore, so a very low cache lifetime is recommended (5 seconds). See section [AuthorizationPerformance]
If more information about the user is required, the OpenID Connect Userinfo endpoint may be called additionally.
Match the ACL with the subject’s roles to make an authorization decisions for the requested resources.

Additional token signature validations using the authorization server’s JWKs set as well as further standard claim checks are obsolete when using the introspect endpoint.