OAuth 2.0 Authorization Framework

This category configures the endpoints that produce the OAuth tokens. Each row in this category represents a configuration item applied on both authorization and token endpoint. The third column presents the current values, while the first two columns determine the applicability of the setting to particular types of requests. The combination of the first two columns determines which requests are supported via the following logic:

This category configures the endpoints that consume the OAuth tokens issued by the authorization/token endpoints. The majority of these endpoints are directly protected by the OAuth Server so that they require the presence of an OAuth access token in the request. The OAuth Server currently supports the transmission of the access token according to RFC6750. The configurable properties of the transmission can be set up for each of the protected endpoints.

Each row in this category represents a configuration item for a single endpoint. The third column presents the current values, while the first two columns determine the applicability of the configuration item to a particular type of request:

DirX Access supports all the RFC6749-listed client authentication methods: client_secret_basic, client_secret_post, and none. During the OAuth authorization process, the authentication methods are employed according to client’s registered metadata. The clients without client credentials must pre-register their redirect URIs.

DirX Access currently does not support communication with unregistered clients, however, it enables any client (even an unknown client) to employ the dynamic client registration mechanism to register to the authorization server and hence enable its use.

The random type of OAuth tokens that represent some form of credentials (access token, authorization code, refresh token, and so on) are generated as random 160-bit strings. This action satisfies the stricter recommendation for prevention against credential guessing by unauthorized parties. More precisely, the random strings are generated by the Java SecureRandom class; consequently, the system administrator can influence the means of their generation by setting up the used Java Cryptographic Service Provider.

The OAuth tokens represented by random strings referencing the authorization information stored on the authorization server rather than stored internally prevents the potential security threat valid for the latter approach. The modification of tokens containing the authorization information may lead to a modification of the information itself and subsequently to authorization elevation.

The validity period of each OAuth token is determined by its type and the use case for which it was created. DirX Access enables configuring the validity period with respect to both of these aspects in the advanced configuration section of the OAuth Server page in DirX Access Manager. The validity is furthermore limited by the validity period of the client metadata. If the time set by client_secret_expires_at in the client metadata of the client to which the token is issued precedes the end of the validity period according to the configuration, the validity period end is set to client_secret_expires_at.

The binding between OAuth tokens and the clients for which the tokens have been issued is tested wherever necessary.

In the current version, the OAuth tokens are not persisted. For the random type of tokens that means a simultaneous restart of all DXA servers leads to a loss of the internal state of those OAuth tokens.

RFC6749 requires the client to use each authorization code only once. Receiving the same code multiple times can, therefore, mean the code was sent by two entities one of which is not the valid client. As the authorization server can’t be sure which receipt is the valid one, it invalidates all tokens (access tokens, refresh tokens, etc.) already issued based on the duplicated code. This feature is fully supported by DirX Access.

DirX Access employs the bearer profile for access token transmission. For more information, see the section “Bearer Token”.

DirX Access enables alternatively to use the JSON Web Token format for the representation of access token. Security of this type of tokens is assured via the signing and encryption. The use case shall determine the necessity of use and parameters of these operations.

The administrator can decide for which use cases the refresh tokens should be issued.

DirX Access also enables refresh token rotation. This mechanism causes a new refresh token to be issued on the use of the original refresh token while the latter is invalidated. This approach effectively shortens the life period of the refresh token and thus the time during which it can be misused.

It also produces a misuse detection mechanism: RFC6749 requires the client to use each rotating refresh token only once. Receiving such a token multiple times can therefore mean the token was sent by two entities, one of which is not the valid client. As the authorization server can’t be sure which receipt is the valid one, it invalidates all tokens (access tokens, refresh tokens, etc.) already issued based on the duplicated token. This feature is fully supported by DirX Access.

With respect to the scopes any client can request (with the exception of UMA 2.0), DirX Access employs a basic rule: the client can be granted only the scopes it has registered in its metadata. This approach enables not only to control the request scopes by the authorization server, but also the features provided to the respective clients, as OpenID Connect and UMA 2.0 requires specific defined scopes to be present in the access tokens.

Client requests scopes and claims that contains resources of the user. A part of these claims is required, but the other part is optional, and the user should be able to choose and grant his consent to some, or none, of these optional claims. For this purpose, there is the User consent page, that is generated based on configuration under the Boolean parameter Print user consent (only for OAuth) or based on prompt request parameter consent (OAuth and OpenID).

The result of the User consent page is then evaluated based on a unique identifier that can be used only once to prevent its potential misuse by sending the consent repeatedly.

With this User consent there is a possibility that the consent won’t be granted by the user itself, but by some script. There is a way to prevent that by implementing CAPTCHA and assure that the consent was granted by the user, but this is not part of the delivered solution.

Maximum Authentication Age specifies the allowable elapsed time in seconds since the last time the user was actively authenticated by the OAuth 2.0 Authorization Framework. The request parameter can also cause reauthentication and it is performed in the same way as the initial authentication.

The display request parameter is an ASCII string value that specifies how the Authorization Server should display the authentication and consent user interface pages to the user.

The supported value is:

The protection API that enables communication between the resource and authorization servers is itself protected by the OAuth 2.0 authorization server. In the DirX Access solution, the authorization server protecting the API is the same instance of the OAuth Server, which enables internal sharing of some important states and thus accelerates the processing.

As defined, PAT is an OAuth 2.0 access token with the scope uma_protection. Following the general rules of DXA OAuth Server configuration, the issuance of PAT is limited to the requesting clients having the uma_protection scope preregistered in their client metadata. Also using the OAuth 2.0 Dynamic Client Registration Protocol, this approach enables easy and automatic management of the UMA resource servers. Any registered OAuth client that contains the uma_protection scope in its metadata is treated as a UMA 2.0 resource server by the DXA UMA 2.0 authorization server.

Any grant type can be used for issuance of PAT; thus DirX Access enables both OAuth client and system users to perform the role of a resource owner.

According to the UMA specifications, the generation of resource identifiers is solely under control of the authorization server. In the DirX Access implementation, the resource identifier is a Base64-encoded 64-bit random value generated by the server during the registration process. The identifier is unique with respect to the resource server.

It is important to point out that the resource identifier is free to be openly published, which justifies the relatively short length of the identifier (there is no requirement on the identifier to be unguessable).

The precise endpoint address is declared in the published authorization server metadata document (found at {issuer}/.well-known/uma2-configuration) and has the following form: {issuer}/rs.

The internationalization of the parameters of resource and scope descriptions is currently not supported.

By default, the user_access_policy_uri parameter in the resource registration response refers to the metadata document of the OData API defined for the policy management. As the response is sent back to the resource server, the server can leverage this information to supply its own specific application to provide the policy management UI to the resource owner.

The administrator can configure the value of the parameter user_access_policy_uri to refer to the address of any custom application that provides the policy management API.

The precise endpoint address is declared in the published authorization server metadata document (found at {issuer}/.well-known/uma2-configuration) and has the following form: {issuer}/permission.

The permission endpoint follows the specification requirements exactly.

According to the specification, the permission request may contain zero or more scopes in the resource_scopes parameter. DirX Access supports the specific case of zero requested scopes but provides a specific way of setting up the authorization policies for this case. For more information, see the section “UMA 2.0 Empty Scopes”.

The precise endpoint address is declared in the published authorization server metadata document (found at {issuer}/.well-known/uma2-configuration) and has the following form: {issuer}/introspect.

To support the UMA 2.0 extension in a configured token introspection endpoint, the extending parameter – permissions – must be included in the Token introspection endpoint section of the OAuth Server configuration object. At the same time, this endpoint’s scopes parameter must contain at least the uma_protection value. Here, the configured scopes enable not only to differentiate between a plain introspection endpoint and a UMA 2.0 extension, but can also provide additional information according to the scopes granted to the access token (PAT for the UMA 2.0 extension) used in the request.

This section describes the DirX Access-specific handling of the non-mandatory items that are relevant to the User-Managed Access 2.0 Grant for OAuth 2.0 Authorization specification.

A client may supply a PCT in the request for RPT. The authorization server subsequently extracts all valid claims internally bound to the PCT and uses them for authorization assessment.

As for the current state, there are no publicly standardized claim token formats. Because DirX Access has other methods for identifying the requesting party, it does not support any claim tokens supplement in the client’s request for RPT.

If the client supplies an existing RPT in the request for a new RPT, the authorization server always upgrades it. As a result:

The authorization server may return a refresh token along with the RPT, depending on the configuration of the token endpoint.

The administrator can configure whether or not the PCT is issued. When the PCT issuance is set to true, the requesting party is explicitly asked for consent with the issuance of the PCT bound to its identity.

The DirX Access UMA 2.0 authorization server extends the token revocation endpoint with the pct OAuth token type to be revocable.

The claims interaction endpoint facilitates the claims collection process between the requesting party and the authorization server. Its precise address is declared in the published authorization server metadata document (found at {issuer}/.well-known/uma2-configuration) and has the following form: {issuer}/claims.

When a request gets to the claims interaction endpoint, the server first checks whether the requesting party has already authenticated to the DirX Access instance. The authentication could have been performed either in previous claims collection rounds or via means irrelevant to the UMA 2.0 scenario (the requesting party has established an active session). If not, the requesting party is provided with the authentication method configured for the Associated Web PEP (either a discrete authentication method, or the corresponding Authentication Application).

The fact the authentication process is bound to the same instance of DirX Access enables the whole process to be accelerated by leveraging an existing DirX Access session. Furthermore, the delegation of the authentication to the Associated Web PEP allows for employing any third-party identity provider (if configured).

The authorization assessment is performed by the resource-centric authorization service. For more information, please see: Resource-Centric Authorization Service.

The authorization server issues an RPT if at least one permission has been granted by the authorization assessment process. In such a case, all the permissions’ validity intervals are set to the same length as the validity interval of the first RPT the permissions are bound to (the RPT may be later upgraded, yet the permissions’ validity will not change).

If an RPT is not issued because the authorization assessment result is negative, one of the following error codes is returned:

This section discusses security considerations related to UMA 2.0 Grant for Oauth 2.0 Authorization.

The support of UMA 2.0 standard can be easily achieved by checking the User Managed Access support checkbox in the Default configuration section of the OAuth Server configuration page in DirX Access Manager (Federation | OAuth | Servers). The administrator may want to customize some of the configuration options. This section explains these options and how they relate to UMA 2.0.

Several examples of UMA-enabled use cases are listed.