Applies to :
- Denodo 8.0
- ,
- Denodo 7.0
Last modified on:
22 Oct 2020
Download: Document

You can translate the document:

Goal

This document explains how to access the published web services with OAuth authentication using PingFederate in the Denodo Platform.

Content

PingFederate enables outbound and inbound solutions for single sign-on (SSO), federated identity management, customer identity and access management, mobile identity security, API security, and social identity integration.

Denodo can publish REST and SOAP web services that require authentication. One of the authentication protocols supported is OAuth 2.0. In this document, we are going to describe how to establish multi-factor authentication in published web services using the PingFederate Oauth 2.0 server. To achieve that we are going to configure OAuth authentication in the Denodo Platform based on the OAuth configuration in PingFederate. This will allow users to access the published web services in the Denodo Platform through OAuth 2.0 authentication using PingFederate.

Summary of the Process

This is what this document describes:

In PingFederate, we are going to cover the following:

Configure the Data store
Configure Password Validator
Configure an Idp Adapter Mapping
Configure the Access Token Management
Configure the Access Token Mapping
Configure the Scopes
Configure the Client

In the Virtual DataPort Administration Tool, we are going to cover the following:

Configure the Virtual DataPort Server with OAuth 2.0
Creating the Scopes as Roles in Denodo
Configure a Web Service to access via OAuth 2.0 Authentication
Invoke the Web Service with OAuth 2.0 Authentication

Configuration in PingFederate

PingFederate exposes a web application for administration ( https://<hostname>:9797/pingfederate/app). Note that we have modified the default port of PingFederate because it collides with one of the Default ports of the Denodo Platform.

Configure the Data store

The First step that we need to do is to configure the Data store to retrieve the user information. Datastores represent external systems where user attributes and other data are stored. Once defined, you can configure PingFederate to retrieve user attributes from datastores for contract fulfillment and token authorization in various use cases.

To create the datastore navigate to the System → Data Stores screen, click the Add New Data Store button to create the required type data store and provide the necessary details. In our case, we have created a LDAP data store for retrieving user information from the Active Directory.

Configure the Password Credential Validator

To use in Identity Providers we can configure a Password Credential Validator. This feature provides centralized credential validation for various PingFederate components and configurations. For instance, LDAP Username Password Credential Validator validates credentials based on an LDAP look-up in an organization's user-datastore.

To manage Password Credential Validators, go to System → Data & Credential Stores → Password Credential Validators. We are going to create a LDAP Username Password Credential Validator. For that we can use the LDAP Data Store created previously.

Configure an Idp Adapter Mapping

Configure an IdP adapter to look up session information and provide user identification to PingFederate. Adapter instances mapped here will be used to authenticate resource owners for OAuth Authorization Code and Implicit grants.

You can map from authentication sources, such as IdP adapter instances or IdP connections, authentication policy contracts, or Password Credential Validator instances (for resource owner credentials) to persistent grants.

You can configure the first stage of the OAuth attribute mapping process in Authentication → OAuth → IdP Adapter Grant Mapping. Select the IdP Adapter on Source Adapter Instance and click Add Mapping. This example uses an instance of the HTML Form Adapter with an instance of the Simple Password Credential Validator.

Configure Access Token Management

PingFederate uses Access Token Management plugins to issue and validate OAuth access tokens. Each plugin instance can have its own token type, configuration settings, and attribute contract.

JSON web token (JWT) bearer access tokens are secure and self-contained tokens. This allows the target resource server to validate the access tokens locally or to send the access tokens to PingFederate for validation. In this example, we have created an instance of type JSON Web Token.

To configure the access token, navigate to the Applications → OAuth → Access Token Management section and click on Create New Instance. On the Instance Configuration tab, add one or more symmetric keys, signing certificates, or both.

In this configuration, provide the Issuer Claim Value which is the value of the Issuer claim (iss) in the JWT, the Audience Claim Value which is value of the Audience claim (aud) in the JWT, JWKS Endpoint Path which is path on the PingFederate server to publish a JWKS with the keys and certificates that the partners can use for signature verification and also provide all other required configuration.

Configure Access Token Mapping

Manage the attribute mapping(s) used to fulfill the access token attribute contracts. This configuration maps from a persistent grant or other sources into the access token attribute contract. For mappings involving a persistent grant, a default mapping should be configured for each access token manager. The default can be overridden based on the context of the authentication event of the original grant.

When mapping a default context, define how PingFederate maps values into the attributes based on the persistent-grant USER_KEY, and any extended attributes defined in System → OAuth Settings → Authorization Server Settings. PingFederate acts as an OAuth authorization server.

Configure the Scope

OAuth provides a mechanism to constrain the privileges associated with an access token, whereas scopes provide a way to more specifically define the privileges requested and granted. Generally, a client specifies the desired scopes when sending an authorization request to the authorization server. If the user approves, the authorization server issues an access token with these scopes.

Scopes are configured globally using the System → OAuth Settings → Scope Management configuration wizard.The scopes are used by denodo server as roles, and it’s mandatory to configure at least one scope in the OAuth Server.

Configure the Clients

An OAuth client application interacts with an OAuth authorization server to obtain the required access tokens to call OAuth-protected services at the resource server. To configure the OAuth clients, go to Applications → OAuth → Clients. Click Add Client and complete the configuration in the Client window.

OAuth defines several different access grant types. Each grant type reflects different authorization mechanisms.

Authorization code (authorization_code): An authorization code is returned to the client through a browser redirect after the resource owner (RO) gives consent to the AS.
Resource owner password credentials (password): This grant type is suitable in cases where the RO has a trust relationship with the client, such as its computer operating system or a highly-privileged application because the client must discard the password after using it to obtain the access token.
Implicit (implicit): A browser redirect responds to the RO authorization request, rather than an intermediate authorization code, and returns an access token to the client. This grant type works for clients incapable of keeping client credentials confidential for use in authenticating with the AS, such as client applications implemented in a browser using a scripting language like JavaScript.
Client credentials (client_credentials): The client presents its own credentials to the AS in order to obtain an access token. This access token is either associated with the client's own resources, and not a particular RO, or with a RO for whom the client is otherwise authorized to act.

In this example, we have configured a client with a grant type as “Authorization code (authorization_code)”.

Configure the Virtual DataPort Server with OAuth 2.0 Authentication

The next step is to configure the Virtual DataPort Server with OAuth 2.0 Authentication. To do this, on the menu Administration, click Server configuration > Server authentication and then, OAuth. Then, select the checkbox ‘Enable OAuth 2.0 authentication for REST and SOAP web services’.

Denodo supports two of the approaches that have been developed to read an access token and obtain its scopes:

JSON Web Token (JWT)
Token Introspection

You need to select the approach that the identity server of your organization supports. In this example we have selected Use JWT to use the mechanism “JSON Web Token (JWT)” to read the access tokens sent by applications.

In this wizard, provide the following details. The values are the same that were added as part of step Configure Access Token Management in the PingFederate setup:

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.

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 that identifies the principal that is the subject of the JWT. Useful in client credential flow when username and password is not provided.

Attribute of the token with user's role (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.

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

Once done with the configuration, you do not need to restart the server to apply these changes.

Creating the Scopes as Roles in Denodo

Before using OAuth authentication for web services, you have to either:

Create the appropriate roles so they match the names of the scopes included in the access tokens.
Or configure the identity manager of your organization so the scopes match the names of the roles you already defined in Denodo.

Remember that you need to grant the “Connect” privilege to the roles, in addition to the other privileges. In the example, we have created the role in the Virtual DataPort for the scope which we created in PingFederate and assign the required privileges to that role.

To create a new role, click Role management on the Administration menu. In this dialog, click New role. In this dialog, you have to provide the following:

The name of the new role.
A description.

Then click Ok. After creating the role, you have to assign privileges to these roles. To do this, select the role and click Assign privileges to assign the required privileges.

Configure a web Service to access via OAuth 2.0 Authentication

Open a REST web service, click on the ‘Edit’ tab,navigate to the ‘Settings’ tab and choose OAuth2.0 under Authentication option.

Save the changes. The Tool will display the “Summary” tab where you can click on “Redeploy” to redeploy the web service for the changes to take effect.

You can also deploy/redeploy using the “Web service container status” table which you can open by navigating to “Tools > Web services container” that lists the existing Web services. Then, you can redeploy the Web service in the embedded Web container. In case of a newly created web service, click on the ‘Deploy’ option.

Invoking the web service with OAuth 2.0 Authentication

In order to access the web service, you need to obtain an access token. We are going to use the OAuth 2.0 credentials wizard in the Virtual DataPort Administration Tool to obtain it. The wizard can be accessed by clicking on OAuth 2.0 wizard on the menu Tools > OAuth credentials wizards of the Administration Tool.

Once you have opened the wizard, follow these steps:

Select the appropriate Authentication grant. Denodo provides different grant types to obtain your token such as Authorization code grant, Resource owner password credentials and Client credentials grant. As we have already configured the client with grant type as Authorization code grant, we are going to choose the same.
Enter the Client identifier and the Client secret provided by the service.
Select one of the options of the Authentication method used by the authorization server. This controls how Virtual DataPort will send the credentials to the service when requesting a new OAuth access token. The options are:

Include the client credentials in the body of the request: Virtual DataPort will add the credentials to the body of the request, in the parameters client_id and client_secret.
Send credentials using the HTTP Basic authentication scheme: Virtual DataPort will send the credentials of the user in the Authentication header of the HTTP request.

Enter the Token endpoint URL.
Only if you selected Authorization code grant, enter the Authorization server URL.
Only if you selected Authorization code grant, select the Redirect URI. When you get to the step 2 of the wizard, you will have to open an URL in your browser. In this URL, the service displays a page where you have to authorize Virtual DataPort to access your data.
Click the plus icon to add the scope and enter its name. Scopes are “privileges” defined by the service, which control the data that the application can request.

Now, click on “Generate the authentication URL”, Virtual DataPort will generate an URL with all the parameters you have provided. Then click on “Open URL”:

This will open a browser like this one, where you need to specify the required credential to allow the access to the specific user:

Copy the generate URL with the code and paste it into the “Paste the authorization response URL” text box.

Click on “Obtain the OAuth 2.0 credentials” and then click on “Copy the credentials to the clipboard”

To consume the REST web service exposed by Virtual DataPort, it is mandatory to send the Authorization Bearer Token with the previously generated token. We can use, for instance, Postman to include the Authentication header and send the request to test it.