OAuth 2.0

BSI IT-Grundschutz 2023 sections covered by this page

• CON.8
• APP.3.1

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf (RFC6749).

An OAuth 2.0 flow has the following roles:

• Resource Owner: Entity that can grant access to a protected resource.
• Resource Server: Server hosting the protected resources.
• Client: Application requesting access to a protected resource on behalf of the Resource Owner.
• Authorization Server: Server that authenticates the Resource Owner and issues access tokens after getting proper authorization (e.g Keycloak).

In terms of RFC6749 the App Suite backend acts as resource server while every user is a resource owner. As a kind of showcase, it is also possible to configure the App Suite to act as authorization server.

Authorization

Granting access to external applications is a two-step process. First the user needs to log in via a special login screen. After this he must grant access to the application on a second screen. All requested permissions and details about the requesting application are shown to him.

After successful authentication a transient session is created. Some OAuth parameters are used as additional input for the cookie hashes. Therefore, those sessions should not be usable outside the authorization context. After granting/denying access the session is terminated again. If the user closes the browser window instead, the session will continue to exist for approximately the configured short term lifetime.

All subsequent requests after signing in, verify the users session based on the provided session ID and secret cookie. If IP check is configured to happen, it will also take place. Auto-login as provided by some well-known OAuth service providers is not supported. A separate sign-in process is currently always necessary.

Using an external authorization server

When using an external authorization server, the internal client and grant management are deactivated. The according provisioning interfaces will not be available, and the "External Apps" section within the App Suite settings page will not show up. The whole client and grant management will be offloaded to the external identity and access management system.

To ensure the validity of incoming access tokens issued by an external identity and access management system, and to grant access to a OAuth 2.0 secured resource, OX App Suite provides two mechanisms that can be activated via configuration. This includes the use of structured tokens Formats such as JWT (RFC7519) or OAuth 2.0 token introspection (RFC7662).

In order to validate incoming JWT, it is necessary to specify where the required signature keys should be fetched from. This can be either an endpoint provided by the external identity and access management system or a local JSON file containing the required JSON Web Key Set (JWKS). If the verification of the signature indicates that it is invalid, an exception is thrown and the JWT is rejected.

When using OAuth 2.0 token introspection, validity is ensured via an introspection request to an introspection endpoint provided by the external identity and access management system. This endpoint returns a JSON (RFC7159) document representing the meta information surrounding the token, including whether this token is currently active.

The definition of an active token is dependent upon the authorization server, but this is commonly a token that has been issued by this authorization server, is not expired, has not been revoked. If the requested token is not active, an exception is thrown and the access token is rejected.

In addition, regardless of the mechanism used, further checks are performed. After the authenticity of the token has been verified, a check is made to ensure that the token has not expired and that the issuing authority inside the token matches the configured one.

Furthermore, the user contained in the token must be able to be resolved into a valid user/context tuple so that the request can be subsequently processed.

If all these preconditions are met, a comparison of the required scopes and the scopes contained in the token is performed to grant access.

See OAuth 2.0 Operator Guide for a complete, and more detailed, list of configuration options.

Using the internal authorization server

OX App Suite is able to act as an authorization server. Again, it is recommended to use an external authorization server. Nevertheless, this setup can be used as a playground.

When using the internal authorization server, some additional restrictions apply. To exacerbate bypassing the authorization flow via the provided screens, a special token is generated by requesting the login screen and needs to be passed around with subsequent requests. Additionally, the referrer header of every request is checked to always reflect the expected former request.

We require the client application to send a state parameter along with the initial request. The authorization code is valid for max. 10 minutes. Exchanging it always results in a refresh/access token pair.

Permissions / Limits

A user may grant access to a maximum of 50 different clients. A user may allow the generation of at most 10 refresh/access token pairs per application. Every further requests will lead to the deletion of the oldest token pair.

An application may request access to every available scope. However, the granted scope is always limited by the user's permissions. If the client requests permissions the user doesn't have, the according scope token will be ignored. The finally granted scope is part of the token response.

It is possible to deny OAuth access at all for certain users via a config-cascade enabled property com.openexchange.oauth.provider.enabled.

Data Storage

OAuth clients are stored within the global DB. Their secrets are encrypted via a configurable static secret. OAuth token pairs are stored within the user DB without any encryption.

Other

Every time a user grants access to an external application, a notification email is sent out to their primary mail address.

Refresh tokens don't expire but can be revoked by both, the user and the client application. Authorization codes consist either of 64 random chars or have a length of 48 chars, where 16 chars consist of encoded user identifiers and 32 chars are random and based on 128bit Java UUIDs. The length is determined by the configured storage: hazelcast (default) or database.

Access tokens have a lifetime of 60 minutes. Every time the client requests a new one the according refresh token is also changed. Access and refresh tokens have a length of 48 chars. 16 chars consist of encoded user identifiers, while 32 chars are random and based on 128bit Java UUIDs.

Client IDs consist of an encoded context group identifier and 256 partially random bits based on two Java UUIDs. Client Secrets consist of 256 partially random bits based on two Java UUIDs. Client redirect URIs must point to HTTPs endpoints unless the host is localhost, 127.0.0.1 or [::1]. This is to ease client development.

API Access

A selected subset of the public HTTP API will be published under the normal path.

The Card- and CalDAV endpoints will be extended to support OAuth directly via the Bearer authentication scheme.