Authentication
Protecting services and resources is paramount to establish access controls and preserve confidentiality. Consequently, NextGen Platform employs a robust architecture for authentication and authorization.
Two primary strategies exist for authenticating users to access resources via APIs over HTTPS:
-
Bearer Token: NextGen Platform supports flexible token validation, including OAuth2 bearer token validation (e.g., Authorization Code Flow) against configured identity providers (IdPs) and validation against a set of API keys.
-
Session Cookie: To seamlessly handle service requests from users already authenticated within the web interface, session cookie validation is supported.
Regardless of whether access is granted through an OAuth2 token, API key, or a logged web session, each method ultimately maps to a specific system user. The internal RBAC model subsequently governs resource access, ensuring consistent permissions irrespective of the authentication method employed by the user.
Bearer Token
Three distinct authentication methods are available for bearer tokens:
-
Access Token: JWT issued via the internal
/tokensendpoint. -
OAuth Token: Validated against an appropriately configured identity provider (IdP) that supports OAuth.
-
API Key: Used for application-to-application (A2A) communication.
Although JWT access tokens issued through the internal endpoint are functional, we strongly recommend utilizing OAuth tokens whenever feasible, as they are regarded as a more secure standard. API keys are instead particularly beneficial for testing, proof-of-concept scenarios, and inter-application communication (A2A).
For all three of the Bearer Token authentication methodologies you can transmit the token by the standard Bearer Authentication header.
Authorization: Bearer <token>
Access Token
Access tokens can be obtained directly by making a POST request to the /tokens endpoint. This request requires the user's username, the associated company, and the password. Upon successful authentication, a JWT access token is issued with a default validity of 8 hours.
The validity period of the token can be adjusted by modifying the company property company.core.waSessionDuration.
To invalidate an issued access token, a DELETE request can be sent to the /tokens endpoint, ensuring that the token is no longer valid for authentication.
For further information, kindly refer to the OpenAPI documentation of your NextGen Platform environment. You can access it via the /api/api-docs endpoint for NextGen Foundation-based applications.
OAuth Token
Identity Providers (IdPs) issue authentication tokens as part of the OAuth2 authentication framework. When a user or client application requests access to a protected resource, they authenticate with the IdP, which then issues an access token. This token serves as proof of authentication and is included in API requests to authorize access.
To ensure secure user authentication, the NextGen Platform service provider validates incoming OAuth tokens. This validation process leverages public keys, dynamically sourced from the configured Identity Provider's (IdP) well-known endpoint, to rigorously verify token integrity and authenticity. This dynamic key retrieval mechanism guarantees that validation remains aligned with current security standards. Adherence to the OAuth standard provides NextGen Platform with a secure, industry-recognized authentication protocol, supplanting the need for less standardized proprietary mechanisms.
For detailed information on configuring the OAuth token validation for NextGen Foundation-based applications, please refer to the following documentation: Single Sign On with OAuth 2.0 protocol
API-KEY
An authenticated user can generate an API key, which acts as a unique identifier, similar to a password, for authenticating API requests.
API keys serve as credentials to verify the identity of the requester, effectively acting as a stand-in for the authorized user who generated them. Consequently, a client configured with a valid API key can perform actions equivalent to the authorized user.
These unique, time-limited tokens are purpose-built for application-to-application (A2A) integrations via REST APIs. They are ideally suited for service accounts, facilitating secure and controlled integration workflows by providing granular authentication and authorization for API access.
For further information on creating or invalidating an API key in NextGen Foundation-based applications, please refer to the provided documentation: API Keys Setting (ENG)
Session Cookie
When a user authenticates through the graphical interface of the application, a session cookie named JSESSIONID is issued.
This cookie can be used as an authentication method when making requests to the REST API by including it in the request headers.
The session cookie remains valid as long as the user's session has not expired, ensuring seamless authentication without requiring additional credentials for each request.