Business Analytics

Introduction

This blog provides a comprehensive, step-by-step guide to configuring an OpenID Connect Authentication Proxy connection using PingFederate as the Identity Provider and LDAP as the backend security directory for IBM Cognos Analytics.

Before diving into the implementation, it’s important to set the right expectations and understand when and why to use an OpenID Connect Authentication Proxy connection instead of a standalone OpenID Connect namespace in Cognos. Additionally, we’ll explore the benefits and drawbacks of this approach.

Why Use an OpenID Connect Authentication Proxy Connection?

An OpenID Connect (OIDC) Authentication Proxy connection in Cognos Analytics allows organizations to use a third-party Identity Provider (such as Azure, PingFederate, Okta, Duo, etc.) to handle user authentication, while still utilizing an existing backend security directory like LDAP or Active Directory (AD) for user authorization. The Identity Provider acts as an intermediary, hence the term "proxy," redirecting authentication requests back to the legacy directory.

In this setup, users are technically logging into the backend security directory (LDAP or AD), but the third-party OIDC provider serves as the first entry point for authentication.

Benefits of Using an OIDC Proxy Connection:

• Maintaining Existing User Identities (CAMIDs): One major advantage of the OIDC proxy is that it does not alter or generate new CAMIDs (Cognos Access Manager IDs) for users who were already authenticated through the legacy system. This avoids the need for a full migration of content, security settings, capabilities, and permissions, which would otherwise be required if creating a separate OIDC namespace.

• Seamless Integration: The proxy approach allows for a smooth transition, ensuring that users retain their access to existing content and security policies without the need for complex user or content migrations. This is especially beneficial for organizations that have significant existing Cognos deployments.

Drawbacks of Using an OIDC Proxy Connection:

• Indirect Login: Users are not truly logging into the new OpenID Identity Provider. Instead, they are still authenticating against the legacy directory (LDAP or AD), with the OpenID provider acting as an intermediary. This means the advantages of modern authentication methods (e.g., multi-factor authentication) offered by providers like Azure AD or PingFederate may not be fully utilized.

• Dependency on Legacy Systems: Since the request from the OpenID Connect Proxy must eventually go to the backend directory (AD or LDAP), Single Sign-On (SSO) between AD/LDAP and Cognos MUST already be functional. If SSO is not correctly set up on the backend, the proxy authentication will fail.

         https://www.ibm.com/docs/en/cognos-analytics/12.0.0?topic=providers-openid-connect-authentication-provider

Technology/Applications Covered:

• IBM Cognos Analytics 12.0.4/11.2.4 Fixpack 4
• PingFederate Identity Server
• LDAP
• OpenID Connect Authentication Proxy
• Webserver(IIS)

Prerequisites for Configuring an OpenID Connect Authentication Proxy with Cognos Analytics:

1. Existing Namespace for Redirection:
   You must have an existing namespace configured in Cognos Analytics (such as Active Directory or LDAP). The OpenID Identity Provider will redirect authentication requests to this namespace.

2. Single Sign-On (SSO) Setup:
   The existing namespace (whether it's Active Directory or LDAP) must have SSO configured with Cognos Analytics. It should function independently and be fully operational, as the authentication process will rely on this integration.

3. Webserver Configured for SSO:

   Depending on the webserver used for the Cognos gateway, it must be configured to handle SSO with Cognos Analytics. The proper setup of Single Sign-On between the webserver and Cognos Analytics can be found in IBM’s official documentation here: Enable Single Sign-On.

4. OpenID Connect Identity Provider:

You must have an OpenID Identity Provider of your choice (e.g., Azure AD, PingFederate, Okta, etc.) to act as the OpenID Connect Authentication Proxy. This provider will handle the primary authentication before passing the request to the backend directory.

Content Overview

1. Configuring the Existing Namespace (e.g., Active Directory or LDAP) with Single Sign-On (SSO)

Before configuring the OpenID Connect Authentication Proxy namespace, ensure that your existing LDAP or Active Directory namespace is properly set up with Single Sign-On (SSO). This includes the following steps:

• SSO Authentication: Ensure that SSO is successfully implemented and tested in Cognos Analytics for the existing namespace.
• Independent SSO Authentication: Verify that the existing security directory (LDAP or Active Directory) allows seamless authentication through SSO without relying on the OpenID Connect integration.

2. Configuring the Webserver for Single Sign-On (SSO) Integration with Cognos Analytics

• Webserver Configuration: Configure the webserver for SSO using the sample templates provided by IBM. These templates can be found in the Cognos Analytics Gateway installation directory under Cognos_Analytics_Gateway_Install\cgi-bin\templates.

3. Configuring the OpenID Connect Authentication Proxy Namespace in Cognos Analytics

Once the existing namespace is properly configured with SSO, proceed with setting up the OpenID Connect Authentication Proxy namespace. The following steps outline the key actions required:

a. Integrating the OpenID Connect Identity Provider

• Identity Provider Selection: Choose your preferred OpenID Connect Identity Provider (e.g., Azure AD, PingFederate, Okta) to serve as the primary authentication source.
• Initial Authentication: The OpenID Connect provider will handle the initial authentication and validate user credentials before redirecting the request to the backend directory (LDAP or Active Directory).

b. Identifying the Identity Claim Name

• Claim Identification: Determine the correct Identity Claim Name, which is the claim (or attribute) from the id_token provided by the OpenID provider. This claim represents the user's identity (e.g., username, email, or UID) and must be formatted in a way that is compatible with the backend security directory.

c. Determining the Trusted Environment Name

• Trusted Environment Name: This string represents the environment variable used to transfer the identity claim to the backend directory. It varies based on the target namespace type (LDAP or Active Directory), ensuring that the OpenID Connect provider passes the validated user identity correctly.

d. Redirect Namespace ID

• Namespace ID: The Redirect Namespace ID is a unique identifier for the target namespace. This value must match the Namespace ID of a pre-configured namespace in Cognos Analytics (such as LDAP or Active Directory) to ensure proper redirection of authentication requests.

Detailed Configuration Steps

1. Configuring the Existing Namespace (e.g., Active Directory or LDAP) with Single Sign-On

For this demonstration, I will be using an LDAP namespace as the Redirect Namespace, where authentication requests from PingFederate will be redirected. To begin, configure the LDAP namespace in Cognos Configuration to use the External Identity Mapping property. This property allows the system to map external identities, such as userPrincipalName or sAMAccountName, to a valid user session variable.At runtime, the resolved value of the External Identity Mapping must be a valid Distinguished Name (DN) in your LDAP directory. This ensures that the authentication request can be appropriately redirected and processed by the LDAP namespace.

For detailed instructions on setting up SSO with an LDAP directory server and configuring External Identity Mapping, please refer to the IBM documentation linked below:

IBM Documentation on SSO with LDAP

For the in-house LDAP Directory Server that we’ve set up, the External Identity Mapping property uses the sAMAccountName attribute. Therefore, in this configuration, we will map the external identity to the sAMAccountName attribute to ensure proper authentication as provided in the example below. 

2. Configuring the Webserver for Single Sign-On (SSO) Integration with Cognos Analytics

 You can configure Single Sign-On (SSO) on the IIS webserver in two ways: using the automated script provided by IBM or configuring the gateway manually. Please refer to the documentation for each approach below:

1. Automated Script Approach

IBM provides an automated script for configuring IIS for SSO. This script can be found in the Cognos Gateway installation directory under the Cognos_Analytics_Gateway_Install\cgi-bin\templates folder. For more details on using this approach, refer to the following documentation:

• Automate IIS Configuration for SSO with IBM Cognos Analytics

2. Manual Configuration of Cognos Gateway

If you prefer to configure the gateway manually, IBM also provides detailed steps for this process. You can find the manual configuration guide here:

• Cognos Gateway Manual Configuration

Key Configuration Notes for SSO on IIS:

To ensure SSO works on IIS, you must ensure the following steps provided below are in-place:

a.Enable SSO Rewrite Rules: Ensure that the SSO rewrite rules under the bi directory are enabled.

b.Windows Authentication: The SSO application under the Cognos Gateway alias should have Windows Authentication enabled. In our setup, Windows Authentication is used to achieve SSO instead of Kerberos authentication.

Once all settings are configured, it's time to test the LDAP namespace to confirm whether SSO functionality is working correctly. To do so, open a browser and navigate to the Cognos Gateway URL. Then, select the LDAP namespace. The expected behavior is that the user will be automatically logged into the Cognos portal using the LDAP namespace, without being prompted for credentials as show in the illustration below. 

3. Configuring the OpenID Connect Authentication Proxy Namespace in Cognos Analytics

a. Integrating the OpenID Connect Authentication proxy Identity Provider

Now that we have successfully configured Single Sign-On (SSO) with the LDAP namespace, we can proceed with setting up the OpenID Connect Authentication Proxy namespace in Cognos. The first step is to create a new namespace of type OpenID Connect Authentication Proxy. This can either be done using a generic template or by selecting an Identity Provider (IDP) vendor-specific template (such as Ping, Azure, or Okta) in the Cognos Configuration, as shown below.

For this demonstration, I’ve chosen to use the generic template. The benefit of using the generic template is the flexibility it provides, allowing for greater control over specific configuration settings compared to vendor-based templates. However, both approaches are viable, and the choice ultimately comes down to personal preference and the specific requirements of your setup.

b. Identifying the Identity Claim Name

Once the OpenID Connect Authentication Proxy namespace is created, the next crucial step is identifying the appropriate Identity Claim Name that will be passed in the id_token issued by the PingFederate Identity Provider. This claim needs to be compatible with the backend LDAP provider, ensuring that the authentication flow functions seamlessly.

To do this, it's essential to revisit the claim mappings on the PingFederate provider and compare them to the user profile attributes from the LDAP server. In this example, the PingFederate Identity Provider is configured with a claim called username, which is mapped to the sAMAccountName attribute in the LDAP user profile. Since the sAMAccountName is also used for authentication in the LDAP namespace (configured under the External Identity Mapping section for SSO), we will use the username claim as our Identity Claim Name in the OpenID proxy configuration. This alignment ensures that the identity token issued by PingFederate will be correctly interpreted by the backend LDAP provider. It's important to note that the specific claim used will vary from organization to organization. Each organization’s Identity Provider and backend directory (whether it's LDAP, Active Directory, etc.) may have different attributes or mappings. Therefore, you must identify and configure the correct claim that fits your specific authentication scenario.

c. Determining the Trusted Environment Name

This string represents the environment variable used to transfer the identity claim to the backend LDAP directory server. In this case, since we are using Windows authentication to achieve Single Sign-On (SSO), we will utilize the REMOTE_USER variable. Microsoft IIS sets this variable by default when the Windows authentication module is enabled. However, depending on how SSO is configured in your specific environment, the variable may differ.

d. Redirect Namespace ID

In the Redirect Namespace configuration, we simply provide the Namespace ID of the LDAP server to which we want to redirect authentication requests from the PingFederate server. This ensures that the requests are properly proxied to the LDAP server for authentication. It’s as straightforward as that—the correct Namespace ID must match the one configured in Cognos Analytics for the LDAP namespace.

This completes the configuration of the OpenID Connect Authentication Proxy namespace. In the next step, we will test the authentication via a browser as show below to ensure that the setup is correctly implemented and all configurations are functioning as expected. 

As demonstrated above, with the OpenID Connect proxy configuration, we successfully authenticated through PingFederate to the LDAP namespace. This can be verified by navigating to Manage > People > Accounts in Cognos Analytics, where you'll see the LDAP directory listed as the active namespace. This confirms the expected behavior since, during login, we selected the PingFederate proxy namespace, which correctly redirected the authentication request to LDAP—ensuring seamless SSO without requiring a direct selection of the LDAP namespace.

Conclusion

In this blog, we have covered the step-by-step process for integrating an OpenID Connect Authentication Proxy namespace with Cognos Analytics using a third-party Identity Provider, such as PingFederate.

While this guide provides a comprehensive approach for configuring OpenID Connect, it's essential to remember that different organizations may have varying requirements based on their infrastructure and security policies. Furthermore, as this setup involves third-party Identity Providers and services outside of IBM's direct control, these configurations may need adjustments over time to align with evolving specifications from those vendors.

The goal of this blog was to offer clarity on setting up the OpenID Connect Authentication Proxy with Cognos Analytics. However, due to the rapid advancement of authentication technologies, IBM does not assume responsibility for potential future changes in third-party vendors' specifications or methods.

As a best practice, always refer to the latest documentation from your chosen Identity Provider (whether PingFederate, Azure AD, Okta, etc.) to ensure compatibility with updates and new features. This helps maintain a robust and up-to-date integration with Cognos Analytics.

#IBMCognosAnalytics#CognosAnalyticswithWatson#CognosAnalytics#Cognos#cognosanalyticssupport#GlobalBusinessAnalytics #CognosAnalytics #Snowflake  #JWT #openidoauth  #Security  #LearnCognosAnalytics #resources #CognosAnalytics #IBMCognosAnalytics #cognosanalyticssupport #CognosAnalyticswithWatson