tibemsOAuth2Params and Environment Variables

Type, Functions, and Environment Variables

Purpose

The tibemsOAuth2Params object, its associated functions and the TIBEMS_OAUTH2_* environment variables are used to directly configure an access token or to set parameters for obtaining OAuth 2.0 access tokens from an authorization server managed by an OAuth 2.0 provider.

Remarks

When establishing a connection to an EMS server configured for OAuth 2.0 authentication, the client must authenticate itself by presenting an access token obtained through one of the following methods.

OAuth 2.0 Grants

Connection factories that are configured with OAuth 2.0 parameters will create connection objects capable of automatically requesting access tokens from an authorization server and using them to authenticate with the EMS server.

Two authorization grant types are supported for obtaining access tokens in this manner: client credentials grant and resource owner password credentials grant. See the tibemsConnection_Create and tibemsAdmin_CreateWithOAuth2Params functions for more information.

Note: Refresh tokens are supported when using the resource owner password credentials grant type. If the authorization server issues a refresh token along with the requested access token, the connection object will use that refresh token instead of the grant the next time it needs to request an access token. If it fails to obtain a new access token using the refresh token, it will try again using the grant.

User-Defined Callbacks

Client applications can define callbacks for obtaining access tokens and register them with connection factories in the form of an OAuth 2.0 parameter. Connections created using a particular factory will invoke the callback any time a new access token is required for authentication. See tibemsOAuth2TokenFetchCallbackEx for more information.

User-defined callbacks take priority over OAuth 2.0 grants. If a callback is registered with a connection factory, connections created using the factory will not attempt to obtain access tokens from an authorization server using OAuth 2.0 grants – even if the relevant OAuth 2.0 parameters for OAuth 2.0 grants are set.

Configured Access Token

Connection factories can also directly be configured with an access token in the form of an OAuth 2.0 parameter. All connection objects created by the connection factory will use the configured access token for authentication. See tibemsOAuth2Params_SetAccessToken for more information.

A configured access token takes priority over both user-defined callbacks and OAuth 2.0 grants. If an access token is explicitly configured for a connection factory, connection objects created using the factory will always use the configured token for authentication - even if the relevant OAuth 2.0 parameters for user-defined callbacks or OAuth 2.0 grants are set.

Note: In the event of access token expiration, connections that use OAuth 2.0 grants or user-defined callbacks will automatically obtain a new access token and re-authenticate with the EMS server. However, connections that use a configured access token will not be able to handle this scenario and will experience authentication failures.

Configuring OAuth 2.0 Parameters

OAuth 2.0 parameters can be configured either through API functions or by setting certain environment variables prior to starting the client application. API functions are the preferred method as they allow fine-grained control over the OAuth 2.0 parameters for each individual connection factory. In contrast, OAuth 2.0 parameters set through environment variables are common to all connection factories created by the application. Parameter values set using API functions take precedence over values set through the corresponding environment variables.

The following functions can be used to configure an tibemsOAuth2Params object. The configured object can be associated with a connection factory or administrative connection using the tibemsConnectionFactory_SetOAuth2Params or tibemsAdmin_CreateWithOAuth2Params functions.

The tibemsOAuth2Params object and associated functions are not supported on z/OS and IBM i systems.

Function	Description
`tibemsOAuth2Params_Create`	Create a new OAuth 2.0 parameter object.
`tibemsOAuth2Params_Destroy`	Destroy an OAuth 2.0 parameter object.
`tibemsOAuth2Params_SetAccessToken`	Set an OAuth 2.0 access token that will be used for authenticating with the EMS server.
`tibemsOAuth2Params_SetClientID`	Set the OAuth 2.0 client ID.
`tibemsOAuth2Params_SetClientSecret`	Set the OAuth 2.0 client secret.
`tibemsOAuth2Params_SetDisableVerifyHostname`	Set a flag that disables client verification of the secure OAuth 2.0 authorization server’s host name.
`tibemsOAuth2Params_SetExpectedHostname`	Set the host name expected to be set in the secure OAuth 2.0 authorization server host’s certificate.
`tibemsOAuth2Params_SetServerTrustFile`	Set the trust file used to verify the identity of the secure OAuth 2.0 authorization server.
`tibemsOAuth2Params_SetServerURL`	Set the URL of the OAuth 2.0 authorization server.
`tibemsOAuth2Params_SetTokenFetchCallback`	Set a callback that will be invoked whenever a regular or administration connection needs to acquire an OAuth 2.0 access token.

OAuth 2.0 authentication can be configured globally for all connection factories and administrative connections by setting the following environment variables prior to starting the client application.

These environment variables are provided primarily to allow existing client applications to employ OAuth 2.0 authentication without making changes to their source code. Where possible, it is recommended to use the API functions instead.

These environment variables are not supported in COBOL, or on z/OS and IBM i systems.

Environment Variable	Description
TIBEMS_OAUTH2_ACCESS_TOKEN	Set an OAuth 2.0 access token that will be used for authenticating with the EMS server.
TIBEMS_OAUTH2_CLIENT_ID	Set the OAuth 2.0 client ID.
TIBEMS_OAUTH2_CLIENT_SECRET	Set the OAuth 2.0 client secret.
TIBEMS_OAUTH2_DISABLE_VERIFY_HOSTNAME	Set a flag that disables client verification of the secure OAuth 2.0 authorization server’s host name.
TIBEMS_OAUTH2_EXPECTED_HOSTNAME	Set the host name expected to be set in the secure OAuth 2.0 authorization server host’s certificate.
TIBEMS_OAUTH2_SERVER_TRUST_FILE	Set the trust file used to verify the identity of the secure OAuth 2.0 authorization server.
TIBEMS_OAUTH2_SERVER_URL	Set the URL of the OAuth 2.0 authorization server.