PingAM as the Identity Provider

This document describes how to configure the PingAM integration for Tetrate Service Bridge (TSB). PingAM integration in TSB allows you to use PingAM as an Identity Provider for user login to TSB, as well as synchronizing users and groups from PingAM to TSB automatically.

Currently, only PingAM 7.4 is supported.

Configuration

PingAM can be configured through ManagementPlane CR or Helm values. Following is an example of a custom resource YAML that uses PingAM as the TSB Identity Provider. You will need to edit the ManagementPlane CR or the Helm values and configure the relevant sections. Please refer to the ManagementPlane PingAMSettings for more details.

spec:
  identityProvider:
    oidc:
      clientId: <clientId>
      scopes: ['username','mail', 'profile']
      redirectUri: https://<tsb-ui>/iam/v2/oidc/callback
      providerConfig:
        dynamic:
          configurationUri: https://<pingam-url>/am/oauth2/.well-known/openid-configuration
    sync:
      pingAm:
        baseUrl: https://cdk.example.com/am
        allowInsecureTLS: true
        realm: /
        clientId: <clientId>

Credential and Certificate

Some operations require running privileged queries against the PingAM server, such as fetching the entire group and user list or authenticating users using a search. In those cases, if credentials are needed, they must be configured in a Kubernetes Secret.

You can use tctl install manifest management-plane-secrets to create the required credentials and certificates to connect to your PingAM server.

tctl install manifest management-plane-secrets --allow-defaults --tsb-admin-password <tsb-admin-password>  \
    --oidc-client-secret=$CLIENT_SECRET \
    --teamsync-pingam-client-secret=$SYNC_SECRET > secrets.yaml

secrets.yaml

apiVersion: v1
kind: Secret
metadata:
  name: iam-oidc-client-secret
  namespace: tsb
type: Opaque
data:
  client-secret: "<oidc application secret>"
---
apiVersion: v1
kind: Secret
metadata:
  name: pingam-credentials
  namespace: tsb
type: Opaque
data:
  client-secret: "<pingam secret>"

Also, create a custom-host-ca secret if your PingAM is configured to present a self-signed certificate:

kubectl create secret generic custom-host-ca \
    --from-file=ca-certificates.crt=<path to custom CA file> \
    --namespace tsb

User and group synchronization

User and group synchronization is done by running the sync queries in the PingAM configuration above. The following example shows an example query that can be used to get a group PingAM server.

groupsFilter: 'cn eq "alicegroup" or cn eq "bobgroup"'

PingAM uses CREST query filters as documented in: https://docs.pingidentity.com/pingam/7.4/am-rest/rest-intro.html#about-crest-query

Configuration Options

The following configuration options are supported for PingAM integration:

Option	Description	Example	Notes
baseUrl	Base URL of the PingAM server.	https://pingam.example.com/am	This endpoint must be reachable from the TSB management plane
allowInsecureTLS	Allows insecure TLS connections when PingAM uses invalid or self-signed certificates.	Default: false	Set to true only in development environments.
realm	The PingAM realm where users and groups are managed, such as employees.	Default: /	Nested realms are currently not supported. Only a single-level realm may be configured.
loginRealm	The realm used when authenticating to PingAM.	Default: /	Some service accounts may require authentication against the root realm even if users and groups are stored in a different realm.
clientId	Client ID configured in PingAM for API access.		This client must have permission to read users and groups. The corresponding client secret must be stored in the Kubernetes secret pingam-credentials under the key client-secret
usersFilter	An optional filter used to restrict which users are synchronized.	usersFilter: "true", usersFilter: 'givenName eq "John"'	This filter must be a valid PingAM CREST query filter expression.
groupsFilter	An optional filter used to restrict which groups are synchronized.	groupsFilter: 'cn eq "platform-admins" or cn eq "platform-users"'	The value must be a valid CREST query filter expression.
pageSize	Number of results returned per page when querying PingAM.	Default: 200	PingAM requires pageSize to be set when retrieving users or groups.