Skip to main content
Version: 19.x (unreleased)

Configure PingFederate as an OIDC Provider

Report an IssueView as Markdown

This guide explains how to configure PingFederate as a single sign-on (SSO) identity provider for Teleport using OpenID Connect (OIDC).

Teleport acts as the OIDC client (relying party) and PingFederate acts as the identity provider. When a user authenticates, Teleport redirects them to PingFederate. PingFederate authenticates the user and returns an ID token containing claims. Teleport evaluates the claims against its claims_to_roles mapping and assigns the appropriate roles.

Prerequisites​

Teleport

  • A running Teleport Enterprise cluster. OIDC connectors require an Enterprise license.
  • A Teleport user with a preset editor role or an equivalent role that allows you to read and write Auth Connectors, users, and roles.
  • The tctl and tsh client tools installed on your workstation. For instructions, see installation.

PingFederate

  • Administrative access to PingFederate.
  • The following configured in PingFederate before proceeding, per the PingFederate OIDC application setup guide:
    • An access token manager.
    • An OIDC policy (unless you plan to use the default policy).
    • Authentication sources mapped to persistent grants.
    • Persistent grants mapped to the access token attribute contract.

Step 1/7. Create an OIDC client in PingFederate​

In the PingFederate administrative console, navigate to Applications > OAuth > Clients and select Add Client.

Configure the following fields:

FieldValue
Client IDteleport-prod-client
Client AuthenticationClient Secret
Grant TypesAuthorization Code, Refresh Token (optional; enables longer sessions without re-authentication)

For the Redirect URI field, use the following value, replacing teleport-host with your Teleport Proxy Service public address:

https://teleport-host/v1/webapi/oidc/callback

Ensure the Authorization Code grant type and the openid scope are enabled, then generate a client secret.

Important

PingFederate does not allow you to retrieve the client secret after creation. Store the secret in a password manager or secrets manager before continuing.

Step 2/7. Configure scopes in PingFederate​

Before associating scopes with the client, confirm each scope is registered globally in PingFederate under OAuth Settings > Scope Management. Then, under Applications > OAuth > Clients > [your client], restrict the client to only the scopes it needs by enabling them in the Allowed Scopes section.

Enable the following scopes for the OIDC client:

ScopeRequired
openidYes
emailYes
profileYes
groupsNo
Groups scope and role mapping

PingFederate does not provide a default groups scope. If you want to use group membership to drive Teleport role assignments, you must configure a custom scope and attribute mapping to include group membership in the ID token. See Step 3/7 for attribute mapping details.

Step 3/7. Configure attribute mappings in PingFederate​

Teleport needs the following claims in the ID token:

OIDC claimPurposeExample PingFederate attribute
subUnique user identifieruid
emailUser email addressmail
groupsRole mappingmemberOf

To configure these mappings, navigate to Applications > OAuth > Clients > [your client] > Attribute Mapping in the PingFederate administrative console and map each PingFederate attribute to the corresponding OIDC claim name.

When a user authenticates, PingFederate issues an ID token that contains claims like the following:

{
  "sub": "[email protected]",
  "email": "[email protected]",
  "groups": ["developers"]
}

Teleport evaluates the groups claim against the claims_to_roles mapping in the OIDC connector to assign the user to the appropriate roles.

Step 4/7. Determine the issuer URL​

Teleport requires the issuer_url to match the issuer field in your PingFederate configuration. Access the PingFederate OIDC discovery document in your browser. Set the issuer_url to the base path of your PingFederate OIDC discovery document endpoint, excluding /.well-known/openid-configuration. For example, if the discovery document endpoint is https://pingfederate-host/.well-known/openid-configuration, then you would use https://varf47832ce6cd04ad48df42db1e760fbce.

Copy this value exactly. Teleport will fail validation if there is any mismatch (such as a missing or extra trailing slash) between this value and your Teleport OIDC connector configuration.

Step 5/7. Create Teleport roles​

Create the Teleport roles that you will map PingFederate groups to. The following example creates a developer role:

kind: role
version: v7
metadata:
  name: developer
spec:
  allow:
    logins: ['ubuntu', 'ec2-user', '{{internal.username}}']
    node_labels:
      env: dev
    kubernetes_groups: ['developers']
    kubernetes_labels:
      env: dev
  options:
    max_session_ttl: 8h

{{internal.username}} is a Teleport template variable that resolves to the authenticated user's Teleport username at login time. It allows the role to grant a login on the target host that matches the user's Teleport identity without hardcoding a username. Remove it if you want to restrict logins to only the explicitly listed values.

Apply the role:

tctl create -f developer-role.yaml

Step 6/7. Create the OIDC connector​

Create a file called pingfederate-connector.yaml with the following content:

kind: oidc
version: v3
metadata:
  name: pingfederate
spec:
  client_id: teleport-prod-client
  client_secret: "<secret>"
  issuer_url: https://pingfederate-host
  redirect_url: https://teleport-host/v1/webapi/oidc/callback
  provider: ping
  display: PingFederate SSO # set to match your branding preferences
  prompt: none # required for PingFederate compatibility
  scope:
    - openid
    - email
    - profile
    - groups # required for claims_to_roles mapping; omit if not using group-based role assignment
  username_claim: sub
  claims_to_roles:
    - claim: groups
      value: developers
      roles:
        - developer
important

Some versions of PingFederate and other Ping products do not support the select_account prompt value. If prompt is omitted, Teleport defaults to select_account, which may cause an invalid_request error during login. Setting prompt: none explicitly avoids this.

Replace the following placeholder values:

PlaceholderDescription
<secret>The client secret you generated in Step 1/7.
https://pingfederate-hostYour PingFederate issuer URL from Step 4/7.
https://teleport-hostYour Teleport Proxy Service public address.
teleport-prod-clientYour PingFederate client ID, configured in Step 1/7.
developersThe PingFederate group you want to map to a Teleport role.
developerThe Teleport role to assign to members of the mapped group.

Before creating the connector, validate it with tctl sso test. This launches a test login flow in your browser without applying the connector, so you can verify the configuration without disrupting an existing connector if you are upgrading:

cat pingfederate-connector.yaml | tctl sso test

Checkpoint: Verify connector configuration

If `tctl sso test` fails, check the following before applying the connector.

Once the test login succeeds, apply the connector:

tctl create -f pingfederate-connector.yaml

You can also apply the connector through the Web UI by navigating to Zero Trust Access > Auth Connectors, selecting Add OIDC, and pasting the YAML content.

Step 7/7. Test authentication​

Log in to Teleport using the PingFederate connector:

tsh login --auth=pingfederate

Verify your session:

tsh status
  • Ensure the username in tsh status output is correct.
  • Confirm the expected roles appear in the output.
  • Verify the cluster connection succeeds.

You can also check the Teleport audit log via Access Monitoring.

Optional: Set PingFederate as the default authentication method for your cluster​

  • To make PingFederate the default authentication method for your cluster, add the following to your Auth Service teleport.yaml and restart the Auth Service:
  auth_service:
    authentication:
      type: oidc
      connector_name: pingfederate

Next steps​