GCP Configuration Using PingFederate as an OpenID Connect Identity Provider

1.0 Introduction

This article outlines the steps required to configure a connection between Fortanix Key Insight, Google Cloud Platform (GCP), and PingFederate as an OpenID Connect (OIDC) Identity Provider (IdP) using the OAuth 2.0 Client Credentials flow.

Federated authentication allows Fortanix Key Insight to authenticate with Google Cloud using short-lived JSON Web Token (JWT) tokens issued by PingFederate, rather than storing static GCP service account keys.

Configuring PingFederate as an OIDC IdP with GCP involves the following steps:

• Configure PingFederate OAuth.

• Verify the PingFederate configuration.

• Configure a Workload Identity Pool and OIDC Provider in GCP.

• Grant the required IAM permissions to the Google Cloud service account.

• Onboard the GCP connection in the Fortanix Key Insight user interface (UI) using the PingFederate OIDC configuration.

WARNING

When configuring Google Cloud with an external identity provider (such as PingFederate), even minor mismatches in configuration (such as issuer URL, audience, claims mapping, or similar settings) can cause authentication failures, often with unclear error messages.

Refer to the official documentation for both Google Cloud and PingFederate for detailed configuration and troubleshooting guidance.

2.0 Prerequisites

Ensure the following prerequisites are met before starting the PingFederate configuration:

2.1 Infrastructure Requirements

The PingFederate server must be deployed and accessible over HTTPS.

The following are the recommended requirements:

• Operating System:

  • Linux: Ubuntu 22.04 or later

  • Windows: Microsoft Windows Server 2016, 2019, or 2022

• Java Runtime: OpenJDK 17

• CPU: Minimum 2 vCPUs

• Memory: Minimum 4 GB RAM

• Disk: Minimum 40 GB of available storage

• Network: Public IP address mapped to a domain name and accessible over HTTPS (static IP address recommended).

For the complete infrastructure requirements list, refer to the PingFederate's official documentation.

2.2 Network Port Requirements

The following network ports must be open to allow proper operation and communication for the PingFederate deployment:

• 22: Used for Secure Shell (SSH) access to the server.

• 80: Used for Let's Encrypt certificate issuance and validation (required only during the initial certificate setup).

• 443: Used for standard HTTPS traffic to securely access the PingFederate application and services.

• 9031: Used for PingFederate runtime services and OIDC endpoints.

• 9999: Used to access the PingFederate Admin Console.

• 389 (optional): Used for LDAP communication when integrating with Active Directory.

• 636 (optional): Used for secure LDAP (LDAPS) communication when integrating with Active Directory.

2.3 PingFederate Requirements

This section lists the software and configuration prerequisites required for PingFederate.

• Java Runtime Environment: Install Java Development Kit (JDK) version 17 and configure the JAVA_HOME environment variable. For more information, refer to the PingFederate's official documentation.

• PingFederate Software: Download, install, and configure the PingFederate 13.x. For more information, refer to the PingFederate's official documentation.

• SSL/TLS Certificate: Configure a publicly trusted Certificate Authority (CA)-signed SSL/TLS certificate (for example, Let’s Encrypt) for the PingFederate domain.

  NOTE

  • GCP Workload Identity Federation only trusts JWT tokens issued from HTTPS endpoints with a CA-signed SSL certificate and rejects self-signed certificates.

  • Certificates issued by Let’s Encrypt are valid for 90 days and should be configured for automatic renewal.

  • The SSL certificate and private key must be convertible to PKCS#12 (.p12) format so that it can be imported into PingFederate keystore.

• Domain Configuration: Configure a Fully Qualified Domain Name (FQDN) that is mapped to the PingFederate server to expose authentication endpoints securely.

  Example: For an Azure Virtual Machine, a DNS name label (for example, my-pingfederate) can be configured for the VM’s public IP in the Azure Portal, which generates an FQDN such as <DNS Name Label>.<region>.cloudapp.azure.com. This FQDN can then be used to access the PingFederate runtime endpoints (<your-domain>) over HTTPS.

• PingFederate SSL Configuration: Import and activate the SSL certificate in the PingFederate Administrative Console to enable secure HTTPS communication.

  For more information, refer to the PingFederate's official documentation.

  NOTE

  Ensure you have administrative access to the PingFederate Admin Console. The URL format of the console is https://<your-domain>:9999/pingfederate/app.

• Base URL Configuration: Configure PingFederate with the correct Base URL (FQDN) that corresponds to the public domain used to expose its runtime endpoints.

• SSL Endpoint Validation: Ensure the PingFederate OpenID Connect discovery endpoint is accessible over HTTPS to verify that the certificate and domain configuration are functioning correctly.

• Ensure you have the ability to create OAuth clients and token managers in PingFederate.

2.4 Google Cloud Requirements

Ensure the following prerequisites are met in the Google Cloud environment:

• GCP project with billing enabled.

• Permissions to create and manage Workload Identity Pools and Identity Providers.

• Permissions to create and manage IAM service accounts.

3.0 PingFederate Oauth Configuration

This section describes how to configure OAuth in PingFederate for JWT-based authentication and integration with GCP Workload Identity Federation.

3.1 Create a JWT Signing Certificate

Perform the following steps to create a signing certificate that PingFederate will use to sign JWT tokens issued to clients:

1. Log in to the PingFederate Admin Console.

2. Navigate to SECURITY → Certificate & Key Management → Signing & Decryption Keys & Certificates.

3. Click Create New.

4. Configure the certificate with the following:

   1. COMMON NAME: Enter the name of the signing certificate. For example, pingfederate-jwt-signing.

   2. ORGANIZATION: Enter the organization or company name creating the certificate.

   3. COUNTRY: Enter the country where the organization is based.

   4. KEY ALGORITHM: Select RSA from the drop down list.

   5. KEY SIZE: Select 2048 bits from the drop down list.

   6. SIGNATURE ALGORITHM: Select RSA SHA256 from the drop down list.

   7. VALID DAYS: Enter the certificate validity period. For example, 3650 days (10 years).

   8. Click Next.

5. Review the configurations and click Save. Ensure to note the Certificate Serial Number for future reference.

3.2 Create an Oauth Scope

Perform the following steps to create a custom OAuth scope used for GCP federation:

1. Log in to the PingFederate Admin Console.

2. Navigate to SYSTEM → OAuth Settings → Scope Management.

3. In the Exclusive Scopes tab, click Add Exclusive Scope.

4. Configure the scope with the following:

   1. Scope Value: Enter a name for the OAuth scope. For example, ping_one_gcp_federation.

   2. Scope Description: Enter a description explaining the scope usage.

5. Click Update.

6. Review the scope and click Save to add the scope.

NOTE

Ensure that both openid and ping_one_gcp_federation scopes are added to the OAuth client configuration to ensure proper PingFederate setup and successful authentication.

3.3 Create an Oauth Client

Perform the following steps to create an OAuth client that will authenticate using Client Credentials:

1. Log in to the PingFederate Admin Console.

2. Navigate to APPLICATIONS → OAuth → Clients.

3. Click Add Client.

4. On the Client page:

   1. CLIENT ID: Enter a unique identifier used by applications to authenticate with PingFederate. For example, gcp_client_id.

   2. NAME: Enter a descriptive name for the OAuth client.

   3. CLIENT AUTHENTICATION: Select the CLIENT SECRET option.

   4. CLIENT SECRET: Click CHANGE SECRET → Generate Secret to create a client secret.

      NOTE

      The Client Secret is displayed only once when it is generated. Ensure to store it securely to use it later.

   5. REDIRECT URIS: Enter the application’s redirect URI (https://armor.fortanix.com/system/discovery/{region}/oauth/callback).

      Here, replace {region} with the appropriate region identifier. For example, eu or na.

   6. RESTRICT COMMON SCOPES: Enable this option to select the available scopes for the client. Select the required scopes from the list.

   7. ALLOWED GRANT TYPES: Select Authorization Code, Refresh Token, and Client Credentials options.

   8. DEFAULT ACCESS TOKEN MANAGER: Select the ATM instance (ki-access-token-management) created in Section 3.4: Create an Access Token Management (ATM) Instance.

5. Click Save to create the OAuth client.

NOTE

• Ensure that you copy the Client ID and Client Secret values, as they will be required when configuring the GCP connection in the Fortanix Key Insight UI.

• PingFederate exposes an OIDC discovery endpoint (well-known URL) that provides configuration details for OIDC clients.

  The endpoint format is https://<your-domain>:9031/.well-known/openid-configuration

  Example: https://krish-pingfederate.westus2.cloudapp.azure.com:9031/.well-known/openid-configuration

3.4 Create an Access Token Management (ATM) Instance

Create an Access Token Manager (ATM) instance that issues JWT tokens for OAuth clients.

Perform the following steps:

1. Log in to the PingFederate Admin Console.

2. Navigate to Applications → OAuth → Access Token Management.

3. Click Create New Instance.

4. On the Create Access Token Management Instance page:

   1. Configure the Type tab:

      1. INSTANCE NAME: Enter a descriptive name for the ATM instance. For example, ki-access-token-management.

      2. INSTANCE ID: Enter a unique identifier.

      3. TYPE: Select JSON Web Tokens as the token type.

      4. Click Next.

      

   2. Configure the Instance Configuration tab:

      1. The Certificates section lists the available signing certificates if they have already been added. For example, the certificate pingfederate-jwt-signing added in Section 3.1: Create a  JWT Signing Certificate.

         Click Show Advanced fields → Manage Signing Certificates → Create New to add a new signing certificate if you have not added any certificates.

      2. TOKEN LIFETIME: Enter the token validity period. For example, 120 minutes.

      3. JWS ALGORITHM: Select RSA using SHA-256 from the drop down.

      4. ACTIVE SIGNING CERTIFICATE KEY ID: Select the Key ID associated with the certificate listed in the Certificates section as mentioned in Step 1.

      5. ENABLE TOKEN REVOCATION: Enable this option to allow tokens to be revoked before their expiration.

      6. ISSUER CLAIM VALUE: Enter the issuer URL in the https://<your-domain>:9031 format. For example, https://krish-pingfederate.westus2.cloudapp.azure.com:9031

      7. AUDIENCE CLAIM VALUE: Enter the OAuth scope value created in Section 3.2: Create an OAuth Scope. For example, ping_one_gcp_federation.

      8. Enable PUBLISH KEYS TO PINGFEDERATE JWKS ENDPOINT option.

         WARNING

         If this option is not enabled, GCP cannot retrieve your public keys to verify JWT signatures. Authentications attempts will fail with error: Unable to verify the ID Token signature.

      9. Click Next.

      

   3. Configure the Token Endpoint Attribute Contract tab:

      1. Add a token endpoint management contract. For more information, refer to the PingFederate's official documentation.

      2. Click Next.

      

5. Click Next in all the remaining tabs.

6. In the Review tab, verify the configuration details and click Save to create the ATM instance.

3.5 Create an Access Token Mapping

Perform the following steps to map your policy contract context to the JWT ATM:

1. Log in to the PingFederate Admin Console.

2. Navigate to Applications → OAuth → Access Token Mapping.

3. On the Access Token Mappings page:

   1. CONTEXT: Select Client Credentials.

   2. ACCESS TOKEN MANAGER: Select the JWT ATM instance created in Section 3.4: Create an Access Token Management (ATM) Instance.

   3. Click Add Mapping.

4. On the Attribute Sources & User Lookup tab, click Next.

5. On the Contract Fulfilment tab:

   1. Contract: Displays the contract created in Step 4.c in Section 3.4: Create an Access Token Management (ATM) Instance.

   2. Source: Select Context from the drop down list.

   3. Value: Select Client ID from the drop down list.

   4. Click Next.

   

6. On the Issuance Criteria tab, click Next.

7. On the Summary tab, review the configuration to complete the mapping  and click Save.

4.0 Verify the PingFederate Configuration

After completing the PingFederate OAuth configuration, perform the following validation checks to confirm that the setup is functioning correctly:

NOTE

When executing the commands, replace <your-domain> with your PingFederate server domain.

• Run the following command to verify the OIDC Discovery Endpoint is accessible:

  curl https://<your-domain>:9031/.well-known/openid-configuration

  Confirm that the JSON response includes the issuer, token_endpoint, jwks_uri, and claims_supported fields.

• Run the following command to verify that the JWKS endpoint exposes the public signing keys:

  curl https://<your-domain>:9031/pf/JWKS

  Ensure the response contains a keys array with at least one entry where kty = RSA and alg = RS256.

  NOTE

  If the JWKS endpoint returns an empty keys array, ensure that PUBLISH KEYS TO PINGFEDERATE JWKS ENDPOINT is enabled in APPLICATIONS → OAuth Server → Access Token Management → <ATM Instance> → Instance Configuration → Show Advanced Fields.

  After enabling the option, save the configuration and restart the PingFederate server to publish the signing keys.

• Run the following command to test OAuth token generation using the Client Credentials grant:

  curl -k -X POST https://<your-domain>:9031/as/token.oauth2 \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    -d "client_id=<your-client-id>" \
    -d "client_secret=<your-secret>" \
    -d "scope=<your-scope>"

  Here,

  • Replace <your-client-id> and <your-secret> with the Client ID and Client Secret values obtained in Section 3.3: Create an OAuth Client.

  • Replace <your-scope> with the scope value created in Section 3.2: Create an OAuth Scope.

  Confirm that the response returns the following fields:

  • access_token

  • token_type (Bearer)

  • expires_in

• Verify the JWT token claims by decoding the generated access_token at https://jwt.io. Confirm the following JWT claims are correct:

  • alg must be RS256.

  • iss must match the PingFederate Issuer URL.

  • aud must match the GCP Workload Identity Provider URL.

  • scope must match the configured OAuth scope.

  • sub must match your Client ID.

5.0 Set Up Workload Identity Federation in Google Cloud Platform

Perform the following steps to configure Workload Identity Federation in GCP platform:

 5.1 Create a Google Cloud Service Account

Perform the following steps to create a Google Cloud Service Account:

1. Sign in to the Google Cloud Console.

2. Navigate to IAM & Admin → Service Accounts.

3. Click Create Service Account.

4. Enter a name and description.

5. Click Create and Continue.

6. In the Permissions (Optional) section, add the required permissions and click Continue.

   For more information on GCP permissions, refer to GCP Connection Permissions.

7. Click Done.

Example: scannerserviceaccount@my-project.iam.gserviceaccount.com

5.2 Create a Workload Identity Pool

Perform the following steps to create a Workload Identity Pool:

1. Navigate to IAM & Admin → Workload Identity Federation.

2. Click Create Pool.

3. Enter a pool name. For example, pingfederate-pool.

   The Pool ID will be populated accordingly.

4. Click Save to add the pool.

5.3 Create an OIDC Provider in the Workload Identity Pool

After creating the pool, perform the following steps to create a new OIDC Provider within the pool:

1. Select a Provider: Select OpenID Connect (OIDC) from the drop down list.

2. Provider Name: Enter a name for your provider. For example, pingfederate-provider. The Provider ID field will be auto-populated with the same value as the name.

3. Issuer (URL): Enter the URL in the following format:

   https://<your-domain>:9031

4. Allowed Audiences: Enter the scope created in Section 3.2: Create an OAuth Scope. For example, ping_one_gcp_federation.

   NOTE

   In the Audiences section, select the Default audience option and copy the displayed value. This value is required later when configuring the GCP connection in Fortanix Key Insight.

   Example:

   https://iam.googleapis.com/projects/<ID>/locations/global/workloadIdentityPools/<POOL NAME>/providers/<PROVIDER NAME>

5. Ensure the Enabled provider toggle is enabled.

6. In the Attribute mapping section, verify the following mapping:

   • Google 1 (google.subject) is mapped to OIDC 1 (assertion.sub)

   • Google 2 (attribute.client_id) is mapped to OIDC 2 (assertion.client_id)

7. Click Save to complete the configuration.

6.0 Grant IAM Permissions in Google Cloud

Perform the following steps to grant access to the required resources:

1. Sign in to the Google Cloud Console and navigate to IAM.

2. Select the required project.

3. Click Grant access.

4. New principals: Enter a principal value.

   Construct this value using the Default audience obtained in Step 4 of Section 5.3: Create An OIDC Provider In The Workload Identity Pool, with the following modifications:

   • Replace https with principalSet.

   • After the workloadIdentityPools name, replace everything that follows with /*

   Example:

   • Default audience: https://iam.googleapis.com/projects/<ID>/locations/global/workloadIdentityPools/<POOL NAME>/providers/<PROVIDER NAME>

     Principal value: principalSet://iam.googleapis.com/projects/<ID>/locations/global/workloadIdentityPools/<POOL NAME>/*

5. Select a role: Select Workload Identity User role.

6. Click Save to assign the required permissions.

7.0 Onboard GCP Connection in Fortanix Key Insight

After completing the PingFederate configuration, provide the following details in Fortanix Key Insight when onboarding the GCP connection using the Client credentials flow:

• Client ID

• Client Secret

• Well-known URL

For more information on configuring an IdP configuration using the Client credentials flow during GCP connections onboarding, refer to Getting Started with Cloud Connection.

8.0 Troubleshooting

For information about common issues and troubleshooting steps when configuring PingFederate with GCP cloud environments, refer to Cloud Connection Troubleshooting.