Introduction
This blog provides an in-depth, step-by-step guide to setting up an OIDC (OpenID Connect) connection with Cognos Analytics using ADFS and Private Key JWT authentication. The process involves securely signing the client ID and JWT (client_assertion) using a private key. Private Key JWT authentication is a method where the client generates and signs a JWT with its private key, which is then transmitted as the client_assertion parameter. Understanding this method is key to implementing secure authentication for applications using ADFS and Cognos Analytics.
This guide demonstrates how to configure an ADFS namespace in Cognos Analytics, utilizing the Token Endpoint Authentication strategy with Private Key JWT. Throughout this blog, the term "client_assertion" will be central, referring to the JWT containing the signed authentication details.
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 secure OIDC connection, but it doesn’t imply that this is the only approach available for such integrations.
Overview
Technologies Involved:
Prerequisites
- A functional ADFS setup
- Cognos Analytics configured with an ADFS namespace
- OpenSSL or a certificate generation tool for creating the key pair
- Any SDK of your choice to generate the client assertion
Content Overview
A.Generating an RSA Key Pair for Private Key JWT
Before configuring an application to authenticate using Private Key JWT, you must first generate an RSA key pair. The private key must be in an encrypted PKCS#8 format and stored in PEM format, as this is the required format for use in Cognos Analytics at the time of writing.
B:Building the client assertion script using the Private Key generated
Client assertion is a JWT signed by the private key when you generated the key pair.
D. Configuring ADFS as an Identity Provider (IDP) with Private Key JWT
This section provides a guide on how to configure ADFS as the identity provider (IDP) to use Private Key JWT for authentication.
E. Configuring the ADFS Namespace to Use Private Key JWT for Token Endpoint Authentication
This section focuses specifically on configuring the ADFS namespace within Cognos Analytics to use Private Key JWT as the strategy for Token Endpoint Authentication.
F. Validating the ADFS Connection in Cognos Analytics
This section will guide you through validating the connection between Cognos Analytics and ADFS.
G. Testing Authentication to Cognos Analytics via ADFS Using Private Key JWT
Finally, this section covers how to test the authentication process to ensure ADFS and Cognos Analytics are properly configured and using Private Key JWT for authentication.
Detailed Configuration Steps
A.Generating an RSA Key Pair for Private Key JWT
In this demonstration, I will show you how to generate an RSA key pair using OpenSSL, a popular tool for handling cryptographic operations. The process will involve creating a private key, a Certificate Signing Request (CSR), and then converting the private key to the required PKCS#8 format for use with Cognos Analytics.
Step 1: Generate RSA Private Key and CSR
The following OpenSSL command is used to generate a new RSA private key and a Certificate Signing Request (CSR) at the same time:
openssl req -new -newkey rsa:2048 -nodes -keyout private.key -out request.csr
- private.key: This file contains the newly generated RSA private key.
- request.csr: This file contains the CSR, which is used to request a certificate from a Certificate Authority (CA).
Step 2: Convert the Private Key to PKCS#8 Format
Next, we need to convert the private key into PKCS#8 format, which is a standardized format for private key storage and the only acceptable format for use with Cognos Analytics.
For more details, please refer to the official Cognos documentation: Cognos Analytics - Generic OIDC Provider.
openssl pkcs8 -topk8 -inform PEM -outform PEM -in private.key -out converted_key.pk8
- converted_key.pk8: This file contains the private key in PKCS#8 format, ready to be used with Cognos Analytics.
Step 3: Submit the CSR for Signing
The final step is to submit the CSR (request.csr) to a Certificate Authority (CA) to have it signed. The CA will return a signed certificate, which you will use along with the converted private key (converted_key.pk8) in your Cognos Analytics environment.
After generating the certificate from the CSR, extract the Key ID (kid) by opening the certificate details and copying the value listed under the Thumbprint section. This value is necessary for building the client assertion .
C.Building the client assertion
To generate a client assertion, you can use an SDK provided by well-known vendors such as Node.js, Python, Java, or C#, depending on your preference. However, for the purpose of this blog demonstration, I will be using Node.js Version 18.20.5 , jose 5.9.6 package and uuid 11.0.3 package to create the client assertion.
For reference, please see the Client Assertion article.
Information Needed to Build the Client Assertion
Before building the client assertion, you will need the following details:
- Private Key: The private key generated in the previous step.
- Issuer: This will be the client ID of the ADFS (Active Directory Federation Services) application.
- Subject: The client ID of the ADFS application (usually the same as the issuer).
- Audience: The token endpoint of the ADFS application (where the assertion will be sent).
- kid(Key ID): The key ID of the certificate generated from the CSR (Certificate Signing Request).
Example: Building the Client Assertion
The following Node.js script demonstrates how to use the jose package to generate a signed JWT (client assertion) with the information you have gathered.
======================================
const { SignJWT } = require('jose');
const crypto = require('crypto');
const uuid = require('uuid');async function main() {
const privateKeyPEM = crypto.createPrivateKey({
key:
`-----BEGIN PRIVATE KEY-----
PRIVATE KEY BODY HERE
-----END PRIVATE KEY-----`,
format: 'pem'
}); const jwt = await new SignJWT({})
.setProtectedHeader({
alg: 'RS256', // or RS384 or PS256
kid: '(Key ID) of the the certificate '
})
.setIssuedAt()
.setIssuer('Client ID of ADFS')
.setSubject('Client ID of ADFS')
.setAudience('https://adfserver.com/adfs/oauth2/token') // Token Endpoint of the ADFS provider
.setExpirationTime('1m')
.setJti(uuid.v4())
.sign(privateKeyPEM); console.log(jwt);
}
main();
====================================
Example client assertion signed with a private key will look like as follows:
C. Configuring ADFS as an Identity Provider (IDP) with Private Key JWT
Now that we have all the necessary information to configure the ADFS application with a private JWT, we can proceed with setting up the ADFS provider. This involves adding the certificate received after signing the CSR. To do so, navigate to the ADFS application created for use with the Cognos application, and add the certificate under the Confidential section and Apply, as shown in the example below.
D. Configuring the ADFS Namespace in Cognos Analytics to Use Private Key JWT
After adding the certificate to the ADFS server, the next step is to configure the ADFS namespace in Cognos Analytics to use the JWT private key. For the purpose of this blog, I assume that the ADFS namespace in Cognos has already been created. Therefore, we will focus only on the relevant sections of the configuration that pertain to the objective of this blog, excluding the broader ADFS setup in Cognos Analytics.
E.Test and validate the ADFS Connection in Cognos Analytics
After providing the information for the Private JWT Key, it is essential to test the ADFS connection from Cognos to ensure that the Test connection to the ADFS namespace is successful as show in the example
F. Authenticating to Cognos Analytics via ADFS Using Private Key JWT
Now that we are in the final stages of implementation and have successfully tested the ADFS connection with the JWT private key, we can conclude the process by performing the final configuration. This includes successfully authenticating with the Cognos application via the browser as shown in the example below: