PingAuthorize

Changing the default JWT claim for the OIDC user ID

You can change the sub JSON Web Token (JWT) claim for the OpenID Connect (OIDC) user ID under the option file’s core section.

About this task

By default, when a user signs on to the Policy Editor with OIDC, the Policy Editor uses the sub JWT claim in the following operations:

  • Extracts the sub claim value from the ID token and:

    • Records the sub claim value in the Creator column of the Commits table when the user makes commits (see Branch Manager → Version Control )

  • Makes a request to the .net/specs/openid-connect-core-1_0.html//UserInfo] endpoint and:

    • Uses the sub claim value from the response as the user data

    • Displays the user data in the upper right of the page

If your organization wants to use a non-default claim for the OIDC user ID, such as email, you can define this claim by completing the following steps.

You must configure your OIDC provider to include the claim in both the UserInfo endpoint and the ID token for the name to display. See your OIDC provider’s documentation for instructions.

Steps

  1. Make a copy of the default options file:

    Example:

    $ cp config/options.yml my-options.yml

  2. In the core section of the new options file, uncomment the example Authentication.oidcUserIdField field that uses the email claim:

    Example:

    core:
# Use a JWT claim other than "sub" for the OIDC User ID.
#
# Authentication.oidcUserIdField: jwt_claim
#
Authentication.oidcUserIdField: "email"

    1. Optional: If needed, change the email claim to your organization’s preferred claim.

  3. Stop the Policy Editor:

    Example:

    $ bin/stop-server

  4. Run setup using the --optionsFile argument and customize all other options as appropriate for your needs:

    Example:

    $ bin/setup demo \
  --adminUsername admin \
  --generateSelfSignedCertificate \
  --decisionPointSharedSecret pingauthorize \
  --hostname  <pap-hostname>  \
  --port  <pap-port>  \
  --adminPort  <admin-port>  \
  --licenseKeyFile  <path-to-license>  \
  --optionsFile my-options.yml

  5. Start the Policy Editor:

    Example:

    $ bin/start-server

  6. Commit a policy change in the Policy Editor at Branch Manager → Version Control.

  7. Verify that your claim is being used.

    1. Select any branch and verify that the new claim value appears in the upper right of the application window.

    2. Verify that the new claim value appears in the Creator column of the Commits table for the commit you made in the previous step.