USER MANUALS

Enabling OAuth Authentication

This page explains how to enable OAuth authentication in Virtual DataPort.

Follow these steps:

  1. Open the Administration Tool and log in with an administrator account.

  2. Click the menu Administration > Server configuration. Then, Server authentication and OAuth.

  3. Choose the mechanism that Virtual DataPort will use to process the OAuth token and obtain its scopes:

    1. JSON Web Token (JWT)

    2. Token Introspection

    Find out if the Identity Provider of your organization generates “JSON Web Token” (JWT); most identity providers do. If it does support JWT, use it because it is easier to set up than “token introspection”.

JWT

Select Use JWT to use the mechanism “JSON Web Token (JWT)” to read the access tokens sent by applications.

OAuth JWT configuration wizard

OAuth JWT configuration wizard

In this wizard, provide the following details:

  • Select the signing algorithm: algorithm used by the issuer to sign the tokens. The public key is going to be recovered using the JSON Web Key Set (JWKS) located at the URL provided below.

  • Issuer: unique identifier of the entity that issues the JWT tokens.

  • Audience (optional): Identifier of the Denodo server as an intended audience. It must be present in the OAuth access tokens that the client applications will send.

    If the access tokens will not include the field aud (i.e “audience”), leave this field empty. Otherwise, the authentication will fail.

    You can configure multiple audience values for which the OAuth access token aud field value will be considered valid.

  • JWKS URL: URL of the JSON Web Key Set (JWKS) of the public keys that are used to sign the tokens that Virtual DataPort will received. The administrator of the Identity Provider of you organization will provide you with this.

    The configuration properties below control the settings of the HTTP connections to the JWKS URL. To change them, use the command SET:

    • com.denodo.vdb.security.OauthAuthenticator.RemoteJWKSet.httpConnectionTimeout: the HTTP connects timeout, in milliseconds, zero for infinite. The default value is 2,000.

      Example of how to set this property
      SET 'com.denodo.vdb.security.OauthAuthenticator.RemoteJWKSet.httpConnectionTimeout' = '10000';

    • com.denodo.vdb.security.OauthAuthenticator.RemoteJWKSet.httpReadTimeout: the HTTP read timeout, in milliseconds, zero for infinite. The default value is 2,000.

    • com.denodo.vdb.security.OauthAuthenticator.RemoteJWKSet.httpSizeLimit: the HTTP entity size limit, in bytes, zero for infinite. The default value is 51,200.

    • com.denodo.vdb.security.OauthAuthenticator.JWKSetCache.expirationTime: the lifespan, in seconds, of the cached JWK set before it expires, a negative value means no expiration. The default value is 300.

    You do not need to restart after executing the “SET” command to change these properties.

  • Subject field name (default value ‘sub’) (optional): name of the parameter in the token that contains the “subject” of the token. I.e. the username of the user that represents the access token. For almost all Identity Providers, the default value of this field is correct.

  • Scope field name (default value ‘scope’) (optional): name of the parameter that contains the scopes of the token. By default, the value of this field is “scope”, but for some authentication servers this could be different.

    In this field, you can enter multiple parameters. For example, if you enter “scope” and “scp”, when Virtual DataPort processes an OAuth token, it will try to read the value of both parameters. If “scp” does not exist in this token, the request will be executed with the roles of the parameter “scope”. If “scope” does not exist, the request will be executed with the roles of “scp”. If both parameters exist, the request will be executed with the privileges granted to the roles of both parameters.

  • Select Check the JWT Id field if the access token contains a JWT ID that can be validated to prevent replication attacks.

    By default, the JWT ID is obtained from the claim jti of the OAuth token. You can change the name of the claim from which the JWT ID will be obtained. For instance, Azure AD tokens include the JWT ID in the uti claim. To do this change, execute this command:

    Command to change the claim to obtain the JWT ID
    SET 'com.denodo.vdb.security.OauthAuthenticator.jwtId' = 'uti';
    Command to restore the default claim to obtain the JWT ID
    SET 'com.denodo.vdb.security.OauthAuthenticator.jwtId' = NULL;

You do not need to restart to apply these changes.

Note

The OAuth authentication mechanism can also process “OpenID Connect” tokens in addition to regular OAuth tokens. From the Virtual DataPort perspective, it does not matter if an access token (OAuth) or an id token (OpenID Connect) are received while all the validations are completed successfully.

Introspection

In order to use the mechanism “Token introspection”, first you need to create a JSON data source. With this mechanism, when a client application connects to Virtual DataPort with OAuth, Virtual DataPort uses this data source to send requests to the Identity Provider, to validate that the OAuth access token sent by the client is valid.

To enable this mechanism, first you have to create a data source that sends requests to the introspection endpoint. According to the standard that defines this mechanism, the requests sent to the introspection endpoint have to meet these requirements:

  • Use an HTTP POST request.

  • The parameters must be URL encoded. The URL is something like http://acme-auth-server.denodo.com:8081/c2id/token/introspect?token=@access_token

  • The parameter with the access token value is token.

  • The parameter token_type_hint may be used to indicate that the token sent is an access token (the standard value in this case is ‘access_token’).

Check the documentation of the Identity Provider of your organization to see if the requirements are others.

JSON configuration wizard

JSON configuration wizard

Once you create this data source, enable OAuth 2.0 authentication.

OAuth introspection configuration wizard

OAuth introspection configuration wizard

  • Database: select the database of the JSON data source.

  • JSON data source: select the data source you just created.

  • Access token interpolated variable: field that contains the value of the interpolated variable with the token.

    For example, let us say you created the JSON data source with this URL: http://acme-auth-server.denodo.com:8081/c2id/token/introspect?token=@access_token

    In this case, the value of this field has to be “access_token”. At runtime, the Denodo server will read the access token from the request and assign it to the interpolation variable “access_token”.

  • Subject field name (default value ‘sub’) (optional): name of the parameter in the token that contains the “subject” of the token. By default, the value of this field is “sub”, but for some authentication servers it is different.

  • Scope field name (default value ‘scope’) (optional): name of the parameter in the token that contains the “scope” of the token. By default, the value of this field is “scope”, but for some authorization servers it is different.

You do not need to restart to apply these changes.

After this, when an application connects to Virtual DataPort with OAuth authentication, Virtual DataPort will send a request to the introspection endpoint, using the data source you have created. The response will indicate if this token is valid or not.

Add feedback