# Configure PingFederate as an OIDC Provider

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](https://goteleport.com/docs/ver/19.x/installation.md).

**PingFederate**

- Administrative access to PingFederate.

- The following configured in PingFederate before proceeding, per the [PingFederate OIDC application setup guide](https://docs.pingidentity.com/solution-guides/customer_use_cases/htg_oidc_app_setup_pf.html):

  - 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:

| Field                     | Value                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| **Client ID**             | `teleport-prod-client`                                                                              |
| **Client Authentication** | `Client Secret`                                                                                     |
| **Grant Types**           | `Authorization 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:

| Scope     | Required |
| --------- | -------- |
| `openid`  | Yes      |
| `email`   | Yes      |
| `profile` | Yes      |
| `groups`  | No       |

---

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 claim | Purpose                | Example PingFederate attribute |
| ---------- | ---------------------- | ------------------------------ |
| `sub`      | Unique user identifier | `uid`                          |
| `email`    | User email address     | `mail`                         |
| `groups`   | Role mapping           | `memberOf`                     |

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": "alice@example.com",
  "email": "alice@example.com",
  "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:

| Placeholder                 | Description                                                 |
| --------------------------- | ----------------------------------------------------------- |
| `<secret>`                  | The client secret you generated in Step 1/7.                |
| `https://pingfederate-host` | Your PingFederate issuer URL from Step 4/7.                 |
| `https://teleport-host`     | Your Teleport Proxy Service public address.                 |
| `teleport-prod-client`      | Your PingFederate client ID, configured in Step 1/7.        |
| `developers`                | The PingFederate group you want to map to a Teleport role.  |
| `developer`                 | The 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
```

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](https://goteleport.com/docs/ver/19.x/identity-governance/access-monitoring.md).

## 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

- Learn how to configure [Multi-Factor Authentication](https://goteleport.com/docs/ver/19.x/zero-trust-access/authentication/per-session-mfa.md) to require MFA on top of SSO.
- Set up [Access Requests](https://goteleport.com/docs/ver/19.x/identity-governance/access-requests.md) to allow users to request elevated roles on demand.
- Review other [SSO connector guides](https://goteleport.com/docs/ver/19.x/zero-trust-access/sso.md) for alternative identity providers.
- Learn more about [OIDC connector reference](https://goteleport.com/docs/ver/19.x/reference/access-controls/authentication.md) for all available connector configuration options.