Using the built in OAuth 2.0 based authentication service

FTL supports authenticating clients using OAuth 2.0 access tokens. When connecting to an FTL server configured with OAuth 2.0 authentication, an FTL client must authenticate itself to the server by presenting an access token issued by an OAuth 2.0 authorization server.

This access token must be a signed JSON Web Token (JWT) that includes claims that the FTLServer can extract to validate that the client has the right FTL role. See https://datatracker.ietf.org/doc/html/rfc7519 for more information on what constitutes a signed JWT token.

The FTL server validates the access token’s signature and claims and accepts or rejects the connection request accordingly. If this authentication process is successful, the FTL client is allowed to connect and access grants based on the FTL role specified in the access token.

In order for an OAuth 2.0 authorization server to issue an access token with the expected claims, the relevant FTL user and group information must be made available to it. Depending on your OAuth 2.0 provider, there may be a number of options available for achieving this. For example, you may be able to define FTL users and groups directly in your provider, or you may be able to integrate your provider with an external authentication service such as LDAP. Refer to your OAuth 2.0 provider’s documentation for instruction.

Obtaining an Access Token

FTL and eFTL clients require an access token to connect to an FTL server configured with OAuth 2.0 authentication. Additionally, an FTL server itself may require an access token to connect to another FTL server or a TIBCO messaging product that is configured for OAuth 2.0 authentication.

Note: FTL only supports access tokens in the form of signed JWTs with asymmetric validation keys. Unsigned JWTs, or JWTs with symmetric validation keys are not supported.

The FTL client APIs, eFTL Client APIs and the FTL server can be configured to use either the Client Credentials grant or Resource Owner Password Credentials grant for obtaining OAuth 2.0 access tokens.

FTL and eFTL clients can set up client side properties that then allow FTL/eFTL client library to retrieve OAuth 2.0 access tokens from the specified OAuth 2.0 provider. Clients may also provide the access tokens that are externally obtained.. These OAuth 2.0 access tokens are then validated by the FTLServer.

Client Credentials Grant

In the Client Credentials grant, the FTL or eFTL client (or FTL server) presents a client ID and client secret to the OAuth 2.0 authorization server. The authorization server uses these credentials to authenticate the FTL client or eFTL client (or FTL server) and issues it an access token.

This is the preferred grant type for both the FTL client and FTL server.

Resource Owner Password Credentials Grant

In the resource owner password credentials grant, the FTL client (or eFTL Client, or EMS server) first authenticates itself to the OAuth 2.0 authorization server by presenting a client ID and client secret, then provides an FTL user and password for validation by the authorization server. If both authentication operations are successful, the authorization server issues an access token to the client.

Refresh tokens are supported with this grant type. If the authorization server issues a refresh token along with the requested access token, the FTL client (or eFTL Client or FTL server) uses the refresh token instead of the grant for requesting the next access token. If it fails to obtain a new access token using the refresh token, it try's again using the grant.

This grant type has been deemed legacy and is expected to be removed in a future update to the OAuth 2.0 framework. It should only be used in situations where the client credentials grant type is not feasible.

Using Externally-Obtained Access Tokens

In addition to the above grant types, the FTL and eFTL client APIs and the FTL server can be configured to use access tokens obtained via external means. If access tokens are directly configured in this manner, the FTL server and client APIs does not attempt to obtain access tokens using the OAuth 2.0 grants.

Note: The FTL client APIs additionally support user-defined callbacks for obtaining access tokens. This method of obtaining access tokens requires the use of new APIs. Existing FTL client applications need to be modified to use the new APIs in order to make use of this method. Refer to the corresponding client API documentation for details.

User-defined callbacks are only available in the client APIs. This method of obtaining access tokens is not supported in the FTL server.

Access Token Expiration

OAuth 2.0 JWT access tokens can have an expiration time specified through the ‘exp’ claim. The FTL server enforces access token expiration by disconnecting the associated FTL client (or eFTL client or FTL server).

Note: FTL server cannot enforce access token expirations in the following scenarios:

  • Authentication is enabled, but TLS is not enabled, and the FTL-generated keystore is present.

  • TLS is enabled with FTL-generated certificates.

In both scenarios, the access token is verified when the client first connects, but FTL server does not disconnect the client when the token expires. It is possible to migrate away from both of the above configurations. See Eliminating the FTL Generated Keystore or Eliminating FTL generated certificates. Once the relevant procedure is complete, access token expirations can be enforced by FTL server.

FTLServer OAuth 2.0 Configuration

To enable OAuth 2.0 authentication, the auth.providers parameter in the FTL server yaml configuration file must contain oauth2 as one of the providers.

In addition, set the following parameters in the FTL server yaml configuration file:

For details, see FTL Server Configuration Parameters

For an example, see samples/yaml/oauth2 in the FTL installation directory.