Business Analytics

Introduction

This blog article offers a detailed step-by-step guide for configuring PingFederate OpenID authentication with Cognos Analytics. The article demonstrates the configuration requires on the PingFederate Server inorder for it to make a successful connection with Cognos Analytics. 

While this tutorial focuses on one specific method of integration, it’s important to acknowledge that alternative methods may also work for achieving similar results. This blog aims to clarify the process and help you implement a Ping Federate OIDC connection, but it doesn’t imply that this is the only approach available for such integrations.

Overview

Technology Involved: 

• Cognos Analytics 12.0.4 and 11.2.4 Fixpack 4
• Ping Federate Server 12.0.1

Prerequisites

1.Ping Federate Server 12.0.1: Working knowledge of Ping Federate Server 

2. Cognos Analytics Server 12.0.2 and 11.2.4 Fixpack 4

Content Overview

The content below is divided into two parts. In the first part, we will focus on configuring the PingFederate provider, which is quite detailed and involves several key components necessary for seamless integration with Cognos Analytics. While you're welcome to explore alternative approaches based on your specific business requirements, the steps provided in this blog have been thoroughly tested in-house and have been proven to work successfully with Cognos Analytics.The second part of this blog with focus on configuring the Cognos Analytics server with Ping Federate provider configured on the first part.

A)Configuring Ping Federating Identity Provider

1. Creating a Datastore Connection to an On-Premises Active Directory Domain
2. Setting Up and Configuring the Password Validator
3. Configuring the IdP Adapter for the Identity Provider
4. Configuring the Authorization Server Settings
5. Defining Scopes in PingFederate
6. Configuring the IdP Adapter Mapping
7. Setting Up Resource Owner Credentials Mapping
8. Managing Certificates and Keys
9. Configuring Access Token Management
10. Configuring Access Token Mappings
11. Setting Up the OpenID Connect Policy
12. Creating the OAuth Client

B) Configuring Cognos Analytics with PingFederate

1. Downloading the PingFederate Certificate for Import into Cognos Analytics

   • Obtain the necessary PingFederate certificate and ensure it is ready for integration.

2. Configuring the PingFederate Namespace in Cognos Analytics

   • Set up the PingFederate namespace within Cognos, ensuring proper authentication and seamless integration between the two systems.

C)Integrating PingFederate with Cognos Analytics for Group Information Retrieval

Cognos Analytics does not automatically retrieve group information from the PingFederate provider by default. Instead, the application only displays the data contained within the id_token issued by PingFederate. Therefore, if group information is not visible in the cogserver.log during authentication, it will not appear in Cognos Analytics either. It is crucial that the PingFederate administrator carefully manages the user group mapping, ensuring that this mapping is included in the id_token and, more importantly, that group information is accessible outside of Cognos before it can be utilized within Cognos Analytics.

The steps in this guide demonstrate how group mapping can be performed by creating a datastore connection to a backend Active Directory, which retrieves user information into PingFederate. This setup involves creating multiple user attributes, with memberOf being the key attribute for obtaining user group information. While this method works in the current setup, it may vary across organizations based on business needs. In such cases, you will need to consult your PingFederate administrator to review how group information is configured and passed in both the id_token and access_token.

Detailed Configuration Steps

A) Configuring Ping Federating Identity Provider

1.Creating a Datastore Connection to an On-Premises Active Directory Domain

The first step is to create a Datastore connection in PingFederate to establish a link to an on-premises Active Directory. This connection is crucial for mapping users from Active Directory to the PingFederate provider, enabling authentication with Cognos Analytics. To begin, navigate to System and select Data & Credentials Stores. Click New Data Store, choose Directory (LDAP) as the type, and then click Next, as illustrated below.

Under LDAP Configuration provide the Hostname of the LDAP Server , the Bind User DN and Password and Test the connection 

   2.Setting Up and Configuring the Password Validator

After setting up the Datastore connection we will need to create a Password Credentials Validator(PCVs) which provides centralized credential validation for various PingFederate components and configurations.

To setup the Password Validator navigate to System and select Data & Credentials Stores. Click Password Credential Validators, click on Create New instance , provide an Instance Name and Instance ID and choose LDAP Username Password Credential Validator as the type, and then click Next, as illustrated below.

In the next step, you'll be configuring the Instance Configuration settings. Here, you'll need to provide key details, including the LDAP Datastore you created in the previous step, the Base Distinguished Name (DN), and the LDAP search filter. These parameters are essential for PingFederate to correctly search and retrieve user information from your Active Directory.

Click Next, which will take you to the Extended Contract configuration. This section is crucial for adding additional LDAP attributes such as memberOf, objectGUID, sAMAccountName, sn, and userPrincipalName. These attributes will be mapped later in Ping to retrieve important user information such as group memberships(memberOf), last name(sn), username(sAMAccountName), and user principal name(userPrincipalName) from the underlying Active Directory provider. These mappings are essential for ensuring the correct user data is available for authentication and authorization with Cognos Analytics.

Finally, we complete the configuration for the Password Validator, which ensures that user credentials meet the necessary security requirements. The final summary of the configuration has been provided below:

 

     3.Configuring the IdP Adapter for the Identity Provider

After completing the configuration for the Password Credential Validator (PCV), the next step is to create an HTML Form Adapter instance. This adapter plays a crucial role in validating user authentication sessions by interacting with the PCV to ensure that credentials meet the required standards.

The primary function of the HTML Form Adapter is to handle and present error messages returned by the PCV during the authentication process. When a user attempts to authenticate, the adapter captures any error messages from the LDAP Username PCV and displays them in a user-friendly format on the HTML form. This ensures that users are informed about issues like incorrect credentials, account lockout, or any other authentication failures.

To configure the HTML Form Adapter navigate to the Authentication tab and select idP Adapters 

Create a New instance and provide the Instance Name, Instance ID and choose HTML Form idP Adapter as Type

Click Next, and you will be taken to the IdP Adapter Settings. This section allows you to configure the user login interaction with PingFederate. For this configuration, we will leave most of the settings at their default values. However, it's important to add the Password Credential Validator (PCV) created in the previous step to the IdP Adapter.

You can add multiple validators if needed and specify the order in which PingFederate should attempt credential authentication. If the first validation mechanism fails, PingFederate will proceed sequentially through the list of validators until the credentials are successfully validated. If none of the configured PCV instances can authenticate the user's credentials, and the maximum number of challenge retries is reached, the authentication process will fail. 

Click Next, and you will be taken to the Extended Contract section. Here, you will need to add all the LDAP attributes of the user that were previously mapped in the Password Credential Validator. These attributes typically include givenName, mail, memberOf, objectGUID, sAMAccountName, sn, and userPrincipalName. These attributes will be used later in the configuration to retrieve important user information, such as the user's groups, full name, username, and other details, from the underlying Active Directory. 

Click Next, and you will be taken to the Adapter Attributes section which is where we will choosing the attribute which we will be using to construct the unique identifier. In this particular case we I will be using the username attribute as the Unique User Key attribute as a pseudonym for account linking to an entity that receives and accepts an authentication assertion issued by an identity provider (IdP), typically for the purpose of allowing access to a protected resource.

We will not be configuring the Adapter Contract Mapping in this particular case. Instead, we will complete the setup of the IdP Adapter by reviewing the Configuration Summary as shown below.

4.Configuring the OAuth Server and Authorization Server Settings

In this section, we will configure the Authorization Server to support the grant types accepted by Cognos Analytics, along with the necessary scopes. Start by navigating to the System tab and then click on Authorization Server Settings

Under Authorization Server Settings, ensure that the section Reuse Existing Persistent Access Grants For Grant Types includes the following grant types: Implicit, Authorization Code, and Resource Owner Password Credentials. However, if the use of Resource Owner Password Credentials (ROPC) is restricted by your company policy, you may opt to use only the Authorization Code grant type.

Under the OAuth Administrative Web Services Settings, ensure that you select the Password Credential Validator that was created earlier.

These are the only two modifications we'll make under the Authorization Server Settings.

5.Defining Scopes in PingFederate

 Next, proceed to create the necessary scopes by navigating to System > Authorization Server Settings > Scope Management. Add the required scopes, such as openid, email, and profile, as shown below.

6.Configuring the IdP Adapter Mapping

In this section we will be configuring the IdP Adapter Mapping. The "IdP Adapter Grant Mapping" in PingFederate allows you to map attributes from the identity provider (IdP) to persistent grants that are issued to clients, such as access tokens or refresh tokens. These grants and their associated attributes remain valid until they expire or are explicitly revoked by PingFederate. To perform the mapping for the IdP Adapter navigate to Authentication tab  select Policy Contract Grant Mapping and click on the IdP Adapter Grant Mapping as show below  

From the dropdown under Source Adapter Instance select the HTML Form Adapter created previously and then click on the Add Mapping

In the "Add Mapping" section, navigate to Contract Fulfillment. Here, you will need to map the necessary values. Under Source, select Adapter and map the USER_KEY to the sAMAccountName, and map the USER_NAME to the username. This ensures that the values retrieved from the identity provider will correctly fulfill the contract for authentication, as shown in the example below.

The only modification we will make in the IdP Adapter Mapping is to map the USER_KEY with sAMAccountName and the USER_NAME with username, as described earlier. Once this mapping is set, the configuration for the IdP adapter mapping will be complete.

7.Setting Up Resource Owner Credentials Mapping

Next, we will perform a mapping for the Resource Owner Credentials by navigating to the Resource Owner Grant Mapping section, which is located under Authentication within the Policy Contract Grant Mapping settings.

Click on the dropdown under Source Password Validator Instance and select the Password Credential Validator (PCV) that was created in the previous steps then click on Add Mapping. This links the validator to the resource owner flow along with the IdP adapter Mapping in place ensuring that user credentials are validated properly during authentication.

In the Add Mapping section, navigate to Contract Fulfillment. Here, you will specify how the user attributes will be retrieved and mapped. Begin by mapping the USER_KEY attribute. Set the Source to the Password Credential Validator (PCV) that was configured in the earlier steps. This ensures the user's credentials are validated correctly. For the USER_KEY, map it to the attribute sAMAccountName, as this uniquely identifies users in Active Directory.

The only modification we will make in the Resource Owner Credentials Mapping is to map the USER_KEY with sAMAccountName. Once this mapping is set, the configuration for the Resource Owner Credentials Mapping will be complete.

8.Managing Certificates and Keys

Next we will navigate to the Signing & Description Keys & Certificates located under Security tab for creating and maintain certificates and their respective key pairs for the purpose of signing outgoing requests, responses, assertions, and access tokens, and for the purpose of decryption.

Click on Create New and proceed to create the certificate by filling in the required details:

1. Common Name (CN): This should be the fully qualified domain name (FQDN) of the server.
2. Organization (Org): Enter the name of your organization.
3. Country: Provide the two-letter country code (e.g., "US" for the United States).
4. Key Algorithm: Choose the appropriate key algorithm, such as RSA.
5. Key Size: Set the key size to 2048 bits, which is a common and secure size.
6. Signature Algorithm: Select RSA with SHA256 as the signature algorithm to ensure secure cryptographic operations.

This process generates a public-private key pair that will be used for signing outgoing communications and encrypting data, enhancing the security of interactions between PingFederate and Cognos Analytics.

9.Configuring Access Token Management

In this step, we will configure the Access Token in PingFederate. To begin, navigate to Applications and select Access Token Management from the menu. This section allows you to manage the lifecycle of access tokens, which are used to authenticate and authorize API requests in PingFederate.

Click on Create New Instance to begin configuring your Access Token instance. Provide a meaningful Instance Name and Instance ID based on your organization's conventions.Make sure to set the Type to JSON Web Tokens (JWT), as this format will be used for securing and transmitting user information, access rights, and authentication claims between PingFederate and Cognos Analytics.

Next, navigate to the Instance Configuration section of your Access Token management. In the Certificates section, add the certificate you previously created under the Key ID field.Once the certificate is selected, proceed to update the JWS Algorithm to RSA using SHA256.Finally, in the Active Signing Certificate Key ID section, set it to the certificate you've added in the previous step. This configuration ensures that the access token will be signed with the correct certificate, maintaining the integrity and authenticity of the token when it's used in the OAuth flow with Cognos Analytics.

In the next step click on Access Token Attribute Contract section and select USER_KEY from the dropdown under Subject Attribute Name and add username under the Extend the Contract section

With the modifications to the Access Token completed, we conclude the configuration process. The overall configuration should now appear as follows, reflecting all the key settings and adjustments we’ve made for integrating PingFederate with Cognos Analytics.

10.Configuring the  Access Token Mapping

Next, we will configure the Access Token Mapping to use the Access Token instance that was created in the previous section. Begin by navigating to the Application tab and selecting Access Token Mappings.

In the Access Token Mappings section click on Add Mapping select Context to Default and set the Access Token Manager to point to the Access Token instance was created in the previous step

Next, navigate to the Contract Fulfillment section under the Contract Set, where the username field will be automatically populated. In this section, set the Source to use the Persistent Grant, and the Value to USER_KEY. This step completes the configuration for Access Token Mappings.

11.Setting Up the OpenID Connect Policy

In this section we will configuring the OpenID Connect Policy which allows us to define OpenID Connect policies for client access to attributes mapped according to OpenID specifications.To begin configuring OpenID Connect policies, go to Applications → OAuth → OpenId Connect Policy Management and click on Add Policy. 

After adding the policy, you will be presented with the Manage Policy section. In this section, provide the following details:

1. Policy ID – A unique identifier for the policy.
2. Policy Name – A descriptive name for the policy.
3. Access Token Manager – Select the Access Token instance created earlier.
4. ID Token Lifetime – Set the desired lifetime for the ID token (e.g., 3600 seconds for one hour).
5. Include User in ID Token – Check the box to include user details in the ID token.

Next, navigate to Attribute Contract and remove any existing attributes that are not required or are irrelevant to the underlying LDAP Datastore created in the initial phase. Retain only the attributes that you want to be passed from Ping Authentication over to Cognos Analytics.This step is crucial, as it determines which attribute values will be included in the ID token, and these are the values that Cognos Analytics will inherit during the authentication process.

Next navigate to the Attribute Source & User Lookup section and create a new Attribute Source by clicking on Add Attribute Source

In the Attribute Source section, provide the Attribute Source ID and Attribute Source Description. Then, select the Active Data Store option, ensuring it points to the LDAP datastore that was created at the very beginning of this implementation.

After completing the previous steps, navigate to the LDAP Directory Search tab. Here, provide the Base DN (Distinguished Name) for the LDAP directory. In the Attributes to Return from Search section, click the dropdown under ROOT OBJECT CLASS and select objectClass. Then, in the ATTRIBUTES dropdown, choose the respective attribute relevant to the selected object class from the list.

Here’s a list of ObjectClass mappings to the corresponding attributes:

InetOrgPerson: displayName, givenName, HomePhone

user: LocalID, userPrincipalName (upn)

top: memberOf, name

person: sn

Next, navigate to the LDAP Filter tab and enter the LDAP filter expression required for the underlying LDAP datastore to fetch the desired attributes successfully. The filter should be customized to ensure the correct user attributes are retrieved based on your organization's specific Active Directory or LDAP structure.Consult with your LDAP/AD administrator to obtain the appropriate filter expression for your setup. 

With this, we have completed the configuration for the Attribute Sources & User Lookup section. Ensure that all settings are saved properly. After saving, head over to the Contract Fulfillment tab, where we will proceed with mapping each attribute to the respective LDAP Datastore.

After configuring the Contract Fulfillment section, save your changes and the final look will look like the one give below

Next  navigate back to Policy Management located under Applications → OAuth. Here, ensure that the policy you created is set as the default policy.

12.Creating the OAuth Client for the OAuth Server

This is the final step of the PingFederate implementation process. We conclude by creating the OAuth Client. To do this, navigate to the Applications tab and select OAuth Clients. Here, you can create a new OAuth client, which will allow you to configure the necessary client credentials and authorize connections between PingFederate and the external applications (such as Cognos Analytics).

Click on Add Client and provide the following information to complete the configuration:

1. Client ID: Choose a unique identifier for the client application.
2. Client Authentication: Set this to Client Secret to ensure secure communication.
3. Generate the Secret: Automatically generate a secret key for the client.
4. Redirect URIs: Provide the Cognos Analytics return URLs in the Redirect URI section. These URLs should match the URLs configured in Cognos Analytics for OAuth.
5. Allowed Grant Types: Set to the following:
   • Authorization Code: For initiating the OAuth flow.
   • Refresh Token: To obtain new tokens when the access token expires.
   • Resource Owner Password Credentials: If you need direct access to user credentials for authentication.
6. ID Token Signing Algorithm: Set this to SHA using SHA-256 under the OpenID Connect settings for secure token signing.

We have now completed the configuration of PingFederate. The next step involves setting up Cognos Analytics with a Ping OIDC namespace. In the following section of this blog, I will guide you through the process of configuring Cognos Analytics to work with PingFederate, covering the setup of namespaces, authentication settings, and ensuring proper integration for smooth operation between Cognos and PingFederate. 

B) Configuring Cognos Analytics with PingFederate

To set up the Ping namespace in Cognos Analytics, the first step is to download the Ping certificate and import the full chain of trust (starting with the root, intermediate, and server certificates) into the Cognos CAMKEYSTORE. This is done by following these steps:

1.Obtain the Discovery Endpoint URL: Begin by pasting the Discovery Endpoint URL into a browser. The discovery endpoint can be obtained from the PingFederate server by navigating to System -> Federation Info. Copy the URL provided in the Base URL section.

2.Append the OpenID Configuration: To form the complete discovery URL, append /well-known/openid-configuration to the Base URL from the PingFederate server, as shown below:

Discovery Endpoint URL :https://hermes1.pingserver.com:9031/well-known/openid-configuration

3.Export the Certificate: From the browser, you can now export the Ping certificate. Make sure to download the full chain of trust, which includes the root, intermediate, and server certificates.

4.Import the Certificate into Cognos

Import the exported certificate chain into the CAMKEYSTORE of Cognos Analytics to ensure that Cognos trusts the PingFederate server's certificate. This is necessary for testing the Ping namespace successfully. To import the certificate, execute the following command from the Cognos Analytics installation directory's bin folder:

 ThirdPartyCertificateTool.jar -i -T -r PingFedServer.cer -p NoPassWordSet

4.Configuring the PingFederate Namespace in Cognos Analytics

To begin configuring the PingFederate namespace in Cognos Analytics, start by creating an OpenID Connect namespace. You have the option to select between a "Ping" or "Generic" OpenID Connect template. For the purpose of this demonstration, I have chosen the "Generic" template because it provides more control over adjusting parameters as needed.

The "Generic" template allows for greater customization and flexibility in terms of setting up authentication parameters and handling various configurations that might be required for your specific integration. 

Once you've selected the "Generic" template for OpenID Connect, proceed to configure the necessary parameters to ensure smooth integration with your PingFederate server. Key settings to align with your PingFederate server include:

• Discovery Endpoint URL: This URL is critical for enabling Cognos to locate the server's OpenID configuration details.
• Client ID: The unique identifier for your application, which should match the client configuration in PingFederate.
• Client Secret: A secure key used for client authentication, ensuring the integrity of the communication between Cognos Analytics and PingFederate.
• Return URL: The URL to which Cognos Analytics will redirect users after authentication. This needs to be configured to allow secure return flow.
• Account Mapping to Claims: It's important to map the appropriate claims from PingFederate to the user attributes in Cognos Analytics, ensuring the system can properly identify and authenticate users.

The final phase in completing the PingFederate and Cognos Analytics integration is configuring Account Mapping within Cognos to align with the attributes set up in PingFederate’s OpenID Connect Policy Management section.

Once the configuration in Cognos is completed with the provided settings, save the changes. After that, proceed to test the PingFederate namespace to ensure that the connection is established successfully.

Lastly, to verify that the PingFederate authentication integration with Cognos Analytics is fully functional, open a web browser and authenticate via the Cognos application URL. This serves as the final step in confirming that the authentication process is working as intended. 

C)Integrating PingFederate with Cognos Analytics for Group Information Retrieval

To ensure that Cognos Analytics retrieves group information from PingFederate, it is important to note that the application does not automatically pull group attributes unless a relevant claim is configured in PingFederate and mapped correctly within Cognos Analytics.

When a user authenticates successfully with Cognos via PingFederate, the default setup only retrieves basic user information without the associated group details unless the group retrieval claim is explicitly added to the account mapping in Cognos as shown below. 

To retrieve the user’s group information, you must first define the necessary claim on the PingFederate side. This claim, responsible for fetching group data from the backend LDAP or Active Directory, should be configured under the OpenID Connect Policy Management section in PingFederate. Once this claim is established, you can map it in the Cognos Analytics account mapping section, ensuring that the groups attribute is correctly assigned and retrieved during the authentication process as shown below.

Alternative Group Configuration: Troubleshooting Steps if the Initial Setup Fails

If the group claim mapping to the memberOf section does not successfully retrieve group information in Cognos from PingFederate, the first step is to enable OpenID Connect (OIDC) tracing. This will allow you to inspect the id_token details in the cogserver.log file.An example of an ID token with groups should look something like the example provided below:

If the group claim is visible in the id_token, we can configure the PingFederate namespace in Cognos to properly map these group claims by adding the following parameters in the Advanced Properties section as shown below:

groupStrategy: "idToken"

groupIdMapping: <group claim name in id_token>

groupNameMapping: <group claim name  in the id_token>

Conclusion

In this blog, we've walked through the entire process of integrating a PingFederate OpenID connection with Cognos Analytics.

While this guide serves as a comprehensive method for configuring this setup, it’s important to note that different organizations may require alternate configurations depending on their specific needs. Additionally, the steps discussed in this blog involve 3rd-party vendors and services that are beyond IBM's direct scope of support. The objective of this blog is to provide a clear understanding of the configurations needed for Cognos Analytics with PingFederate. However, due to evolving technologies, IBM does not assume responsibility for potential future changes in 3rd-party vendors' technical specifications or processes.

It's always advisable to consult the latest documentation from PingFederate or any relevant 3rd-party provider for updates on procedures or configurations. This ensures that your integration remains compatible with future changes or enhancements that the vendors may introduce.

 

#IBMCognosAnalytics#CognosAnalyticswithWatson#CognosAnalytics#Cognos#cognosanalyticssupport#GlobalBusinessAnalytics

#CognosAnalytics   #JWT #openidoauth  #Security  #LearnCognosAnalytics #resources #CognosAnalytics #IBMCognosAnalytics #cognosanalyticssupport #CognosAnalyticswithWatson