OAI-Secure

OAI-Secure is the recommended login mode in Cumulocity. This tab describes the OAI-Secure session configuration and the available token generation options, as well as how to retrieve a platform token using an X.509 certificate over standard HTTPS.

To select OAI-Secure as the preferred login mode for your tenant, switch to the Basic settings tab.

OAI-Secure session configuration

OAI-Secure is a more secure alternative to the Basic Auth mode that also supports username and password login. In OAI-Secure mode the credentials in the initial request are exchanged for a JWT token that is set as a cookie in the web browser or returned in the response body. Based on the configuration OAI-Secure can support full session management or work as a standard JWT authentication where the user session lifetime is limited by the token expiration time.

When there is no configuration related to the session, OAI-Secure issues a JWT token with a certain lifetime. If the token expires then the user is forced to re-login because token refresh is not supported. This behavior is very inconvenient for the user if the token lifetime is short because the user is forced to re-login frequently.

OAI-Secure with the configuration of the session management (session configuration turned on)

Using OAI-Secure with session configuration is more convenient and secure, and can be used to achieve a behavior which is similar to the authentication based on HTTP sessions.

The OAI-Secure token acts as a session identifier on the client side (web browser). Such a token identifier which is stored in the cookie can have a preconfigured short lifetime. Then, the Cumulocity platform is responsible for renewing the session identifier without any user interaction. It is sufficient that the user’s action causes the web browser to send a request to Cumulocity. Then, Cumulocity can examine if the renewing of the session identifier should be executed and perform the operation if necessary. Cumulocity offers extensive configuration related to this behavior so that tenant administrators can adjust the configuration to their needs.

If the Use session configuration option is enabled, the following settings can be configured on tenant level by a tenant administrator:

Field	Description	Default
User agent validation required	If turned on, the user agent sent in headers of consecutive requests in the scope of one session will be compared and a request with changed user agent will not be authorized.	false
Session absolute timeout	Defines the maximum period of time that the user can use Cumulocity without having to re-authenticate.	14 days
Session renewal timeout	Expected to be much shorter than the absolute timeout. Defines the time after which Cumulocity tries to provide a new token (session identifier). The renewal may take place only when Cumulocity receives an HTTP request from a client with a non-expired token and the period of time between obtaining the token and the execution of the request is greater than the renewal timeout.	1 day
Maximum parallel sessions per user	Defines the maximum number of sessions which can be started by each user (for example on different machines or browsers). When a user exceeds this limit, then the oldest session will be terminated and the user will be logged out on this particular device.	5 sessions
Token lifespan	Defines the time for which a token is active. The user is only able to access Cumulocity with a valid token. This configuration option is always available, it does not depend on session configuration. See Token generation with OAI-Secure below.	2 days

Info

The time parameters should depend on each other in the following manner: renewal timeout < token lifespan < absolute timeout. Moreover, the renewal timeout should be approximately half of the token lifespan.

Therefore, the recommended settings for a standard use case for OAI-Secure are the following:

Session absolute timeout: 28 800 seconds (8 hours)
Session renewal timeout: 2700 seconds (45 minutes)
Token lifespan: 5400 seconds (90 minutes)

In such configurations, the idle timeout is in the range of 45 to 90 minutes, depending on when the last activity for the session was performed.

During the session token renewal the previous token is revoked and a new one is provided. The parameter renewal token delay defines the delay used to make this process smooth and not disturbing for the user. The old token is still valid for this period (1 minute by default). This way both tokens, old and new, are accepted by Cumulocity. This parameter is only configurable on platform level and cannot be modified by the tenant administrator.

Token generation with OAI-Secure

OAI-Secure is primarily based on JWT stored in a browser cookie. It can be also used to generate JWT in the response body. The lifespan of the tokens and the cookie is configurable by tenant options belonging to the category oauth.internal.

JWT tokens stored in the browser cookie have a default validity time of two weeks. This can be changed with tenant options:

category: oauth.internal;
key: basic-token.lifespan.seconds;

The minimum allowed value is 5 minutes.

For generating a token stored in a cookie, see Cumulocity OpenAPI Specification.

Lifespan configuration of cookies

Cookies used to store a JWT token in a browser have their own validity time that can be changed with tenant options:

category: oauth.internal;
key: basic-user.cookie.lifespan.seconds;

The default value is two weeks. To have the cookie deleted when the user closes the browser, set it to any negative value.

Lifespan configuration of JWT in response body

The lifespan of JWT tokens generated in the response body is configured with the following tenant options:

category: oauth.internal;
key: body-token.lifespan.seconds;

Refer to the Tenant API in the Cumulocity OpenAPI Specification for details on the tenant options. For generating a token in the response body, see Cumulocity OpenAPI Specification.

Retrieving a platform token using an X.509 certificate

Cumulocity provides a REST endpoint that lets a client obtain a platform API access token by presenting an X.509 certificate over standard HTTPS (port 443), without requiring mutual TLS or MQTT. This is useful for clients that cannot use MQTT or the dedicated mTLS REST endpoint (typically exposed on port 8443) because of firewall, network, regulatory, or operational constraints.

The client sends its PEM-encoded leaf certificate or certificate chain to the endpoint and receives a platform access token in return. By default, the token is returned as a JWE encrypted with the public key from the presented certificate, so that only the holder of the corresponding private key can decrypt and use it; a plain JWT response is available only if that mode is explicitly enabled. The encryption profile (JWE compact serialization with RSA-OAEP-256 and AES-256-GCM) requires RSA certificates.

The endpoint reuses the existing certificate validation and tenant trust configuration: the certificate chain must be trusted according to the tenant’s trust configuration, the same way as for device authentication with certificates. This tab does not repeat how trusted certificates (CA certificates) are uploaded and managed. For those details refer to:

Connecting devices using certificates for an introduction to certificate-based authentication and X.509 certificates.
Managing trusted certificates for uploading and managing the trusted (CA) certificates in a tenant.

Info

Unlike the existing device certificate authentication, this endpoint is not limited to device users. A token can be issued for any eligible Cumulocity user type — device users, regular users, and microservice service users — provided the user exists in the tenant and is eligible for certificate-based authentication.

The endpoint is intentionally reachable without bearer-token authentication, because the submitted certificate and the platform-side certificate validation are the authentication proof. Invalid, expired, revoked, untrusted, unsupported, or unmapped certificates are rejected.

For the request and response details, including the required headers and the supported token response modes, see Cumulocity OpenAPI Specification.

Important

A single certificate Common Name (CN) can potentially resolve to more than one Cumulocity user. For example, a regular user may be represented by the username derived directly from the certificate CN (my-client), while a device user may be represented by applying the device_ prefix to the same CN (device_my-client).

If a certificate identity resolves to more than one eligible user, the platform does not choose one implicitly. Instead, the token request is rejected and no token is issued (fail-closed behavior). This prevents the same certificate from being used silently for different user identities.