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 JWK configuration wizard

OAuth JWK 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 to the JSON Web Key Set of public keys that can be used to sign an authentication token. This is provided by the OAuth authentication server.

  • 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.

You do not need to restart to apply these changes.

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.