The following changes have been made to the PingOne APIs or the associated SDKs.

More information

For more information about PingOne product updates, see Release Notes.

If you want to start building your own workflows with PingOne APIs, the Workflow Library provides step-by-step workflows with linked Postman collections to help you start using the PingOne APIs in your Postman environment.

PingOne API domains

The PingOne API includes the following regional domains.

• api.pingone.com, api.pingone.ca, api.pingone.eu, api.pingone.asia, and api.pingone.com.au

  These are the primary domains for calling PingOne Management API resource server, with api.pingone.com used for environments in the North America region (excluding Canada), api.pingone.ca for environments in the Canada region, api.pingone.eu for environments in the European Union region, api.pingone.asia for environments in the Asia-Pacific region, and api.pingone.com.au for environments in the Australia region.

  The {{apiPath}} variable in the sample requests represents the regional domain for the PingOne server. This variable stands for https://api.pingone.com/v1 for environments in the North America region (excluding Canada), https://api.pingone.ca/v1 for environments in the Canada region, https://api.pingone.eu/v1 for environments in the European Union region, https://api.pingone.asia/v1 for environments in the Asia-Pacific region, and https://api.pingone.com.au/v1 for environments in the Australia region. Note that the trailing /v1 is required.

• auth.pingone.com, auth.pingone.ca, auth.pingone.eu, auth.pingone.asia, and auth.pingone.com.au

  This is the authorization and authentication server domain called to request the access token required to authenticate PingOne API requests, with auth.pingone.com used for environments in the North America region (excluding Canada), auth.pingone.ca for the Canada region, auth.pingone.eu for the European Union region, auth.pingone.asia for the Asia-Pacific region, and auth.pingone.com.au for the Australia region.

  The {{authPath}} variable in the sample requests represents the regional domain for the PingOne authentication server. This variable stands for https://auth.pingone.com for the North America region (excluding Canada), https://auth.pingone.ca for the Canada region, https://auth.pingone.eu for the European Union region, https://auth.pingone.asia for the Asia-Pacific region, and https://auth.pingone.com.au for the Australia region. Note that nothing trails the domain in the {{authPath}} variable.

• orchestrate-api.pingone.com, orchestrate-api.pingone.ca, orchestrate-api.pingone.eu, orchestrate-api.pingone.asia, and orchestrate-api.pingone.com.au

  These are the primary domains for calling the PingOne DaVinci Management API resource server, with orchestrate-api.pingone.com used for environments in the North America region (excluding Canada), orchestrate-api.pingone.ca for environments in the Canada region, orchestrate-api.pingone.eu for environments in the European Union region, orchestrate-api.pingone.asia for environments in the Asia-Pacific region, and orchestrate-api.pingone.com.au for environments in the Australia region.

  The {{orchestratePath}} variable in the DaVinci requests documentation represents the regional domain for the PingOne server. This variable stands for https://orchestrate-api.pingone.com/v1 for environments in the North America region (excluding Canada), https://orchestrate-api.pingone.eu/v1 for environments in the European Union region, https://orchestrate-api.pingone.ca/v1 for environments in the Canada region, https://orchestrate-api.pingone.asia/v1 for environments in the Asia-Pacific region, and https://orchestrate-api.pingone.com.au/v1 for environments in the Australia region. Note that the trailing /v1 is required.

• scim-api.pingone.com, scim-api.pingone.ca, scim-api.pingone.eu, scim-api.pingone.asia, and scim-api.pingone.com.au

  These are the primary domains for calling the PingOne System for Cross-domain Identity Management (SCIM) API resource server, with scim-api.pingone.com used for environments in the North America region (excluding Canada), scim-api.pingone.ca for environments in the Canada region, scim-api.pingone.eu for environments in the European Union region, scim-api.pingone.asia for environments in the Asia-Pacific region, and scim-api.pingone.com.au for environments in the Australia region.

  The {{scimPath}} variable in the SCIM requests documentation represents the regional domain for the PingOne SCIM server. This variable stands for https://scim-api.pingone.com for environments in the North America region (excluding Canada), https://scim-api.pingone.eu for environments in the European Union region, https://scim-api.pingone.ca for environments in the Canada region, https://scim-api.pingone.asia for environments in the Asia-Pacific region, and https://scim-api.pingone.com.au for environments in the Australia region.

PingOne API region codes

For the relevant endpoint properties (as shown in the data models for the endpoint), the regions supported by the PingOne API are referenced using these region codes:

The Try A Request feature

Except for the authentication and authorization requests, our documentation for the PingOne APIs includes an interactive Try A Request feature. Try A Request enables you to configure and send a PingOne API request and get a response from within the documentation. This is a quick way to interactively test a PingOne API request without needing to use either Postman or the command line.

Calling the PingOne APIs from the command line

Each PingOne API request in the documentation includes an example request and response. By default, the example request is displayed using cURL. However, a number of coding languages are available in the associated drop-down list. If you want to run a request from the command line, you can select the coding language and copy the displayed request. You'll need to replace any variables in the request with the appropriate values before running the request.

Using Postman collection-level authorization

Most APIs require authorization to ensure that client requests access data securely. Postman can pass along whatever authorization details necessary for the method demanded by the endpoint. You can manually include authorization data in the header, body, or as parameters to a request. However, the easiest way is to use the Authorization tab in Postman. Select an authorization Type on that tab and Postman offers a dialog to gather the information required by that Type. When you run a request, Postman uses the information from the Authorization tab to automatically add the necessary authorization header, body, or parameters to the request. Postman offers the Authorization tab on requests, folders, and collections.

In PingOne collections, the authorization method is defined at the collection level. Only those requests that require a specific authorization method have authorization defined on the request (roughly 10% of PingOne requests). This allows you to easily change the authorization used for most requests. See Postman Collection-Level Authorization for more information.

Related topics

This section provides guidance on what PingOne API client developers should do to maintain forward compatibility of their client applications as PingOne APIs evolve. PingOne is a continuously developing platform, and developers must be aware of non-breaking changes to the APIs and how to prepare for these inevitable changes. PingOne will rarely, if ever, introduce a breaking change; however, when that happens, there will be notifications or deprecation messages to inform developers. For non-breaking changes, client developers must ensure that their apps will function as expected after the following API changes occur.

Non-breaking API changes

Client applications should be resilient to additions of new optional properties in request and response payloads. The following list of enhancements occur regularly to the Pingone platform API.

Related resource links

The addition of new related resource links added to responses should not cause application breaks in your client environments.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "organization": {
            "href": "https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda"
        },
        "license": {
            "href": "https://api.pingone.com/v1/organizations/bed432e6-676a-4ebe-b5a5-6b3b54e46bda/licenses/3f06970a-3235-46cb-b46f-cf6dfee2bb84"
        },

Almost all PingOne API responses include a _links section that lists related resources as HAL (Hypertext Application Language) links, and these lists change as the platform adds new resources (and new relationships). For common endpoints such as /environments or /users, the list of HAL links changes often.

New optional properties

The addition of new (optional) properties added to request and response payloads should not cause application breaks in your client environments.

PingOne API endpoints, even those that have been part of the platform since its inception, can receive additional optional data model properties as the platform matures. Client application developers must configure their client environments to accommodate new optional properties in requests and support new returned properties in endpoint responses.

New content-types or content-language formats

The addition of new content-types or content-language formats of the same resource should not cause application breaks in your client environments.

The platform API includes endpoints that support multiple content types. Client application developers must configure their application environments to accept supported media types for the endpoint. For example, the following request shows a new action on the /{{envID}}/flows/{{flowID}} endpoint that supports a device authorization grant. Your client environment should support the new content type, application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json.

curl --location --request POST '{{authPath}}/{{envID}}/flows/{{flowID}}' \
--header 'Content-Type: application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json' \
--data-raw '{
    "userCode": "{{userCode}}"
}'

New HTTP methods

The addition of new supported HTTP methods added to a resource should not cause application breaks in your client environments.

Client application developers must configure their application environments to accommodate new HTTP methods added to a platform service. For example, adding a new PATCH operation to an endpoint should be supported in your client environments.

Third-party libraries

Some third-party libraries deployed in your client environment can cause failures as a result of the non-breaking API changes listed above. In such cases, configuration of the library objects can resolve the issue.

For example, if your application environment uses the Jackson library to serialize or map Java objects to JSON, it is recommended that you update the object mapper setting responsible for deserializing API responses to prevent deserialization errors when new properties are added to the API response. The recommended setting is: new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);. (Jackson's default setting is true.)

As a backup, you can also annotate Jackson library objects with the @JsonIgnoreProperties(ignoreUnknown = true) property to prevent deserialization errors. Conservative developers may choose to employ both strategies.

Protocol for breaking changes

Ping Identity will only support the current release of the platform APIs.

APIs and resources that are made generally available to all customers for Ping Identity’s multi-tenant hosted service products are designed to evolve in a non-breaking fashion rather than rely on versioning to change. In the case of a breaking change that requires an API or a resource to be versioned, the following describes the Ping Identity version support lifecycle:

• The current version of the API or resource will be supported;

• Once a new version of the API or resource is released, the previous version will also be supported for one (1) year; and

• After this one (1) year period, previous versions of the API or resource will no longer be supported.

For information about integrating PingOne services with other Ping Identity products, see the following integration guides:

• To integrate the PingOne platform with PingFederate, see Federating PingOne and PingFederate.

• To integrate PingOne MFA with PingFederate, see Overview of the PingOne MFA Integration Kit.

• To integrate PingOne Risk with PingFederate, see Overview of the PingOne Risk Integration Kit.

The PingOne integration catalog API enables developers to discover and retrieve integration metadata and download integration kits as a compressed file. For more information, see Integration Catalog. For use cases, see Download an integration binary in PingOne for Developers.

Related topics

API clients can experience latency when creating resources across services in the PingOne platform multi-region architecture, where the newly created resource has not propagated through the system to allow for the successful completion of a follow-up request. For example, if you create a resource with one internal service, it is possible that other internal services might not be aware of that new resource in time for your code's next step. An immediate call to the second resource can fail. Given this potential for latency, all applications should be written to retry the request.

The primary areas that experience latency are:

• Applications and Secrets

  Latency occurs when you create an application and then try immediately to retrieve the system-generated secret.

• Applications and Scopes

  Latency occurs when you create an application and then try immediately to retrieve its resource access grants.

• SAML configuration and attributes

  Latency occurs when you create a SAML configuration and then try immediately to retrieve its attribute mappings.

• Environments, role assignments, and applications

  Latency occurs when you create an environment and then try immediately to retrieve its role assignments or add an application to the new environment.

• Populations and role assignments

  Latency occurs when you create a population and then try immediately to retrieve its role assignments.

The PingOne Authentication API provides services to query the authorization server, run authentication workflows, and receive access tokens from the authorization server. An authentication workflow can include local authentication actions (login), multi-factor authentication actions, and other external actions. The Authentication API includes the flow orchestration and action services needed to configure an authentication workflow.

The authorization service allows a resource owner (you) to share protected resources with a client (an application) without giving the application your password (or access to all your stuff). Instead, the resource owner interacts with an *authorization server (PingOne) that verifies your credentials and issues an access token to the client. The client uses the token to access only the protected resources stored on a resource server (your stuff) that you've granted, as specified by the scopes (permissions) defined in the token.

The flow service provides the authentication actions to complete the checks needed to confirm that it's you. For example, if the authentication flow requires a username/password check (a login action) and a one-time passcode check (an MFA action), then both actions must be completed successfully before the authorization server can issue an access token.

A typical flow starts with a request to the PingOne authorization server. The authorization server returns a flow ID that initiates the authentication flow. After the flow service completes, the session is passed back to the authorization service to generate the access token. The diagram below shows the steps.

In the authorization and authentication API sample requests shown in this document, the {{authPath}} variable in the sample requests represents the regional domain for the PingOne authorization and authentication services. See PingOne API domains for more information.

The PingOne Authentication API includes the following entities.

Authorization server

The PingOne authorization server (as) service configures the authorization grants that are used to authenticate users and provide access to resources. This service includes the following entities:

• authorize

  Queries PingOne (or an external resource owner) to get an authorization grant.

• resume

  Continues the processing of an authorization request after the completion of an authentication flow.

• userinfo

  Returns claims about the authenticated user resource.

• token

  Obtains an access token by presenting its authorization grant.

• jwks

  The JSON Web Key (jwks) is a JSON representation of the cryptographic key.

• .well-known/openid-configuration

  The discovery endpoint, used in multi-tenant configurations to support multiple issuers per host.

• signoff

  The end session endpoint called by the flow orchestration service to initiate the logout flow.

For more information, see OpenID Connect/OAuth 2 and Application authorization and authentication.

Flows

The PingOne flow orchestration service configures the steps required to authenticate the application or user that initiated the authentication request. The service is responsible for initiating the authentication session and making calls to specific actions required by the authentication workflow.

For more information, see Flows and PingOne flow states.

OAuth 2 and OpenID Connect

OpenID Connect is an authentication protocol that PingOne connected applications can use to authenticate users and get user data through claims. PingOne can also act as an OAuth 2 authorization server to authorize clients to access protected resources using access tokens. For example, PingOne uses OAuth 2 to protect access to PingOne management APIs.

The OAuth 2 framework defines several methods by which a client can obtain authorization to access protected resources using an access token. The access token represents authorization granted to the client for a set of scopes. Scopes are string identifiers understood by both the authorization server and the resource server to represent the specific boundaries of access. The client can use the access token as a credential for accessing data on a resource server.

For more information about access tokens, see Access tokens.

SAML 2.0

The SAML service provides support for the SAML protocol to authorize clients and allow clients to obtain a requestor’s authentication state. The SAML service implements functions to initiate SAML 2.0 single sign-on and single logout authentication flows.

For more information, see SAML 2.0.

Related topics

The following topics provide information about the platform's advanced configuration options in authorize and token requests.

• Redirect and non-redirect authentication flows

  Describes the authorize request's response_mode options, which include the query, fragment, and form_post options for redirecting back to the client. It also describes how to use the PingOne pi.flow custom response option for non-redirect flows, returning response parameters encoded as a JSON object directly to the client.

• Create a login_hint_token JWT

  Describes the claims required by the login hint token, and how to sign the JWT using an application's client secret as the signing key.

• Create a request property JWT

  Describes the claims required by the request property token, and how to sign the JWT using either the application's client secret or a private key as the signing key.

• Create a client secret JWT

  Describes the claims required by a JWT used to authenticate the PingOne /token request, and how to sign the JWT using an application's client secret as the signing key.

• Create a private key JWT

  Describes the claims required by a JWT used to authenticate the PingOne /token request, and how to sign the JWT using a private key as the signing key.

• Create a private_key_jwt JWKS string

  Describes how to configure a JWKS string (or JWKS URL) to add to an application configuration to enable the use of a private key JWT as the authentication method for a PingOne /token request.

The response_mode authorization service property provides the mechanism for returning authorization response parameters from the authorization endpoint. In PingOne, the response_mode property's options are query, fragment, form_post, and pi.flow. The query, fragment, form_post options are defined in the OAuth 2.0 Multiple Response Type Encoding Practices specification.

When redirecting back to the client using the redirect_uri property:

• query

  The response parameters are encoded in the query string added to the redirect_uri.

• fragment

  The response parameters are encoded in the fragment added to the redirect_uri.

• form_post

  The response returns a form_post encoded response, and after user approval, returns a result in an HTTP POST to the client.

The pi.flow option is a Ping Identity custom response mode to specify that the redirect_uri parameter is not required and authorization response parameters are encoded as a JSON object wrapped in a flow response and returned directly to the client with a 200 status. For example, with native mobile apps and SPAs that want to render the end-user interface, setting the response_mode property to pi.flow allows the app to authenticate using the flows API without needing to handle HTTP redirections. When authentication is complete, the app receives the auth code, access token, or ID token in a JSON response instead of a redirect.

Use cases for pi.flow

The following outlines several use cases for a non-redirect flow using the pi.flow option for the response_mode property. For application integration use cases (including PingFederate), a login_hint_token is also specified in the authorize request to specify the application ID and the associated user ID.

The login_hint_token must be a signed JWT in which the iss claim is the ID of an enabled application and the aud claim is the platform issuer URL. For example:

{
  "iss": "{{integratedAppID}}",
  "sub": "{{userID}}",
  "aud": "https://auth.pingone.com/{{envID}}/as",
  "iat": 1300819380,
  "exp": 1300819391
}

The JWT must be signed using the HS256, HS384, or HS512 algorithm and the application's client secret as the key.

Integrations with PingFederate

The PingFederate PingOne MFA adapter uses the response_mode property with the pi.flow option. For detailed information about integrating PingFederate and PingOne MFA, see PingOne MFA Integration Kit.

Non-redirect flow for mobile clients

A non-redirect flow for mobile clients implements custom flow interfaces with PingOne platform flow APIs but with native application interface components. PingOne can be used for complete authentication or MFA only by providing a login_hint_token with the already authenticated user context on the authorization request.

The following sample shows an authorize request for the non-redirect flow:

{{authPath}}/{{envID}}/as/authorize?response_type=token id_token&response_mode=pi.flow&scope=openid profile email&state={{string}}&login_hint_token={{loginHintJwt}}&client_id={{clientID}}

Transaction approval flows

PingOne supports transaction approval when strong authentication is required for elevated security for a high-value transaction, or high-risk resource or service. The authorize request includes the response_mode and request parameters. The request property value is a JWT that enables OIDC/OAuth2 request parameters to be passed as a single, self-contained parameter.

The following sample shows an authorize request for a transaction approval flow:

{{authPath}}/{{envID}}/as/authorize?response_type=token id_token&response_mode=pi.flow&scope=openid&state={{string}}&request={{requestString}}&client_id={{clientID}}

PingOne support for response_mode options

The following table shows the current support for response_mode options for specific response_type values in the authorize request.

A login_hint_token is a JWT that provides a way for the client to identify and authenticate the end-user without needing to encode the entire authentication request in a signed JWT. The following information describes the OIDC parameters and the steps for generating and signing the token.

Prerequisites

1. Install a JWT token generator such as jwtgen globally using npm install -g jwtgen. This action requires npm.

2. Retrieve the environment id property value associated with your worker application and user.

3. Retrieve the clientId and clientSecret property values for the worker application.

4. Retrieve the user ID id or username property value for whom this token will be associated.

Generate a signed token

The header parameters cty and enc must not be included in the login_hint_token JWT header. PingOne does not support nested signing or encryption operations here.

The command to generate the login_hint_token JWT takes the following parameters:

1. Run the jwtgen command.

jwtgen -a "HS256" -s "YOUR_CLIENT_SECRET" -e 3600 --claims '{
"iss":"YOUR_CLIENT_ID",
"sub":"YOUR_USER_ID_OR_USERNAME",
"iat":1300819380,
"exp":1300819391,
"aud":"https://auth.pingone.com/YOUR_ENVIRONMENT_ID/as"
}'

2. Record the token returned successfully by the command to use as the value of the login_hint_token property in the authorize request.

A request property JWT enables OIDC/OAuth2 request parameters to be passed as a single, self-contained parameter. Using a JWT enables integrity protection of parameters that are required for risk-based authentication or privacy and consent use cases.

You can create a request JWT using the following signing algorithms:

• HS256, HS384, HS512

  Use this signing algorithm when an application's client secret is the signing key.

• RS256, RS384, RS512

  Use this signing algorithm when an external private key is used as the signing key.

For example, the request JWT for a transaction approval action takes the following parameters:

Request property JWT signed using the client secret

This sample shows the information required in a transaction approval JWT in which the JWT is signed using the PingOne client secret with HS256 encryption:

"jwtHeader": {
  "alg": "HS256",
  "typ": "JWT"
},
"jwtBody":
{
  "aud": "https://auth.pingone.com/{{envID}}/as",
  "iss": "{{appID}}",
  "pi.template": {
    "name": "transaction",
    "variant": "{{variantName}}",
    "variables": {
      "sum": "1,000,000",
      "currency": "USD",
      "recipient": "Charlie Parker"
    }
  },
  "pi.clientContext": {
    "alert.color": "red"
  }
}

This sample demonstrates the use of the pi.webAuthn.challenge parameter for using dynamic linking to attach a unique identifier to a FIDO transaction:

"jwtHeader": {
  "alg": "HS256",
  "typ": "JWT"
},
"jwtBody":
{
  "aud": "https://auth.pingone.com/{{envID}}/as",
  "iss": "{{appID}}",
  "pi.webAuthn": {
    "challenge": "1cd774777136450c97e83267a52cecccb5f52d1adbc0f46c42e164edadb47fb3"
  }
}

The following information describes the OIDC parameters and the steps for generating and signing the token.

Prerequisites

1. Install a JWT token generator.

2. Retrieve the environment id property value associated with your application and user.

3. Retrieve the clientId and clientSecret property values for the application.

4. Retrieve the name of the transaction notification template that you want to use.

Generate a signed token

1. Run JWT token generator, providing the information above.

2. Record the token returned successfully by the command to use as the value of the request property in the authorize request.

Request property JWT signed using a private key and JWKS string

This sample shows the information required in a transaction approval JWT in which the JWT is signed using an external private key with RS256 encryption:

"jwtHeader": {
  "alg": "RS256",
  "typ": "JWT"
},
"jwtBody":
{
  "aud": "https://auth.pingone.com/{{envID}}/as",
  "iss": "{{appID}}",
  "pi.template": {
    "name": "transaction",
    "variant": "{{variantName}}",
    "variables": {
      "sum": "1,000,000",
      "currency": "USD",
      "recipient": "Charlie Parker"
    }
  },
  "pi.clientContext": {
    "alert.color": "red"
  }
}

Generate a keypair

1. Use a keypair generator to create a keypair with the following configuration options.

   • Key size: 2048

   • Key use: signature

   • Algorithm: RS256

   • Key-ID: SHA-256

   • Show X.509: No

2. Save the generated Public and Private Keypair and the Public Key.

   • Example public and private keypair

     {
     "p": "x1mRR-Y1_i8ZPTLe2sPmuif4hhIfaxSph8m_iACDEHvAfTh0RMV7SrExscRSUXzcWX_FbSIKE5tDm4c1qzImnmWz06z6SSQYUjl0iU6V439sebR662deH5kOF92Vbtj5OLk-mNdj-fm6CdwnWEp3vb36T9kOiKHGReluwJpG1I8",
     "kty": "RSA",
     "q": "tY0osG4YzkzTX_NCxN3QBFinw_hvJLX6zVXZ-PGHTOD0iFsdwCzmqa3o6_4-GtHUSiuoboTscx2ItbU824IDp41p99HLvSm0lZixszqlcG1JZSaQVj5_5rOBttTcovvAL5te4jq5Mi966WC3yT-V_ZLxE3jFNt5vNzW8ykxsAJ8",
     "d": "T_2qcj4Tb-wuMCvI3uOvBZza21PjzkCy5iTClT3QZ30Wlwm8A35x1b3MVHz7JGox3I_KvMClwQdrDMU2aibQaGzs_EunMH5Y1VhlKDg4RvuQBoyB9lpDT1TdrmDe7kHDPDERrB84gPQkrAm-RgJ0W_zPyJMR013pZjOwPKlxKYbsW1G02Jbg2Vl1zatNWBm1MFYQYEOYyaNQkt32WktNdgixYg0Qdt3Q160mbfNz5c9USLVqvCsye0J2t9DZPK7WzadQCC4S7ehdmQkGd87IfD4XyKuZND_nE8Nz5nbgOLNfuIwR6QH7ksOHT9ur1JVKkzEkX8P40_7LXdarwraiBQ",
     "e": "AQAB",
     "use": "sig",
     "kid": "q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us",
     "qi": "t06uC_ML8E01gKSeFPH7LNFxpumuIaYBc_Enr10dB-wqGpYfs6B5yqf5SjlXg1K89Z3QZFcU9AdJW0SYtr9T-A7b3csxeWUW98hOwfXentP8vcSv3dXJI753f64tAZqz5Mgd6jh0D8i1Fvg6d7Hqm_a5cfd-DO80QkW9c8u8rmk",
     "dp": "L95hFWvBQVUb8WcavltWNxNMCR2m77aZcuLOHCFLV5TvxuHcgXsOPQRJk4852RlrbA5TYP5Qfx7EYD9acs5rGZQAV27s9s01DeGAC0yUj3lUmfDtp0M-BcZh7PcnX-O4DJfm4RqvhiIiOyXjSL8w-5330l6jr8lw6-6-yn8BTR8",
     "alg": "RS256",
     "dq": "lFS9ftClEcCxHn7Y-ZGkyDhK8ZFD9YF9ZVCUY5GqksRk5hdTylSlLNL7L_0sbqsrQGJFHe8aZL8nmBZ4n3utUrL2dlSBmo69jVARN7ddvep8gdktKlmsFChrfZ6SmdMIZZ0Su9FwyDEEwjKUVifOezwYHWmZ78dypHASTFJ-F08",
     "n": "jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q"
     }
     

   • Example public key

     {
     "kty": "RSA",
     "e": "AQAB",
     "use": "sig",
     "kid": "q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us",
     "alg": "RS256",
     "n": "jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q"
     }
     

Generate a signed JWT

1. Create a signed JWT with Algorithm RS256 and header and payload information shown below.

   • Header

     {
      "alg": "RS256",
      "typ": "JWT"
     }
     

   • Payload (for the transaction approval example)

     {
      "aud": "https://auth.pingone.com/{{envID}}/as",
      "iss": "{{appID}}",
      "pi.template": {
        "name": "transaction",
        "variant": "{{variantName}}",
        "variables": {
          "sum": "1,000,000",
          "currency": "USD",
          "recipient": "Charlie Parker"
        }
     }
     

2. Record the token returned successfully.

2. Record the token returned successfully by the command to use as the value of the request property in the authorize request.

Create the JWKS string

You will use the generated keys to create a JWKS string object that can be used as the value in your PingOne application’s jwks property.

1. Copy the Public Key and wrap it like this:

   {
   "keys": [
     <Your public key>
    ]
   }
   

   Which looks like this:

   {
   "keys": [
      {
        "kty": "RSA",
        "e": "AQAB",
        "use": "sig",
        "kid": "q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us",
        "alg": "RS256",
        "n": "jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q"
      }
    ]
   }
   

2. The string needs to be reduced to one line and the double quotes escaped.

   The JSON for the PingOne application POST (or PUT) to create the application looks like:

   {
     ...
     "tokenEndpointAuthMethod": "PRIVATE_KEY_JWT",
      "jwks": "{ \"keys\": [ { \"kty\": \"RSA\", \"e\": \"AQAB\", \"use\": \"sig\", \"kid\": \"q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us\", \"alg\": \"RS256\", \"n\": \"jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q\" } ]}",
     ...
   }
   

Configure the JWKS URL

To use the jwksUrl property in the PingOne application's configuration, the JWKS string must be hosted on a web server, accessible to the internet (using https://). For testing purposes, the following code sample shows a simple node server file (running on a local web server) that hosts the JWKS string.

const https = require("https");
const host = 'localhost';
const port = 3000;

const requestListener = function (req, res) {
    res.setHeader("Content-Type", "application/json");
    res.writeHead(200);    

    const jwksString = "{\r\n  \"keys\": [\r\n    {\r\n        \"kty\": \"RSA\",\r\n        \"e\": \"AQAB\",\r\n        \"use\": \"sig\",\r\n        \"kid\": \"q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us\",\r\n        \"alg\": \"RS256\",\r\n        \"n\": \"jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q\"\r\n    }\r\n  ]\r\n}";

    res.end(jwksString);
};

const server = https.createServer(requestListener);
server.listen(port, host, () => {
    console.log(`Server is running on https://${host}:${port}`);
});

With the JWKS string in a known location, the application configuration JSON looks like this:

{
  ...
  "tokenEndpointAuthMethod": "PRIVATE_KEY_JWT",
  "jwksUrl": "https://{{pathToJwksString}}",
  ...
}

The CLIENT_SECRET_JWT property is a supported value on the application's tokenEndpointAuthMethod property. This client authentication method uses the application's client secret to sign a JWT, which is passed in as a property to authenticate the token request.

For JWT-based client authentication, the token supports the following required and optional claims.

Other properties of the JWT are:

• The optional iat and jti claims from the JSON Web Token (JWT) spec are not validated. See RFC7523 JWT Format and Processing Requirements.

• The JWT can include other claims in addition to those listed above.

• The JWT must be signed. For CLIENT_SECRET_JWT signing, the platform supports only the HS256, HS384, and HS512 symmetric keyed hashing algorithm.

• The JWT must be valid.

Prerequisites and workflow

The following information describes the OIDC parameters and the steps for generating and signing the JWT.

1. Retrieve the environment id property value associated with your application.

2. Retrieve the clientId and clientSecret property values for the application.

3. Install a JWT generator.

4. Generate the signed JWT using the JWT generator. To create the client_secret_jwt JWT, the token generator will require values for the following parameters:

5. Record the JWT returned successfully by the JWT generator.

Use the JWT in a token request

For applications that set the tokenEndpointAuthMethod to CLIENT_SECRET_JWT, the token request requires the following two properties:

• client_assertion

  A JWT that contains a signed assertion with the application’s credentials. This is the JWT that you generated and signed with your application's client secret.

• client_assertion_type

  A string that specifies the client assertion type. The value of this property must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

For more information about the token request, see Token.

The PRIVATE_KEY_JWT property is a supported value on the application's tokenEndpointAuthMethod property. This client authentication method uses an external private key to sign a JWT, which is passed in as a property to authenticate the token request.

For JWT-based client authentication, the token supports the following required and optional claims.

Other properties of the JWT are:

• The optional iat and jti claims from the JSON Web Token (JWT) spec are not validated. See RFC7523 JWT Format and Processing Requirements.

• The JWT can include other claims in addition to those listed above.

• The JWT must be signed. For PRIVATE_KEY_JWT signing, the platform supports the RS256, RS384, and RS512 symmetric keyed hashing algorithm.

• The JWT must be valid.

Generate a keypair

1. Use a keypair generator to create a keypair with the following configuration options. This example uses the RS256 signing algorithm (RS384, and RS512 are also supported).

   • Key size: 2048

   • Key use: signature

   • Algorithm: RS256

   • Key-ID: SHA-256

   • Show X.509: No

2. Save the generated Public and Private Keypair and the Public Key.

   • Example public and private keypair

     {
     "p": "x1mRR-Y1_i8ZPTLe2sPmuif4hhIfaxSph8m_iACDEHvAfTh0RMV7SrExscRSUXzcWX_FbSIKE5tDm4c1qzImnmWz06z6SSQYUjl0iU6V439sebR662deH5kOF92Vbtj5OLk-mNdj-fm6CdwnWEp3vb36T9kOiKHGReluwJpG1I8",
     "kty": "RSA",
     "q": "tY0osG4YzkzTX_NCxN3QBFinw_hvJLX6zVXZ-PGHTOD0iFsdwCzmqa3o6_4-GtHUSiuoboTscx2ItbU824IDp41p99HLvSm0lZixszqlcG1JZSaQVj5_5rOBttTcovvAL5te4jq5Mi966WC3yT-V_ZLxE3jFNt5vNzW8ykxsAJ8",
     "d": "T_2qcj4Tb-wuMCvI3uOvBZza21PjzkCy5iTClT3QZ30Wlwm8A35x1b3MVHz7JGox3I_KvMClwQdrDMU2aibQaGzs_EunMH5Y1VhlKDg4RvuQBoyB9lpDT1TdrmDe7kHDPDERrB84gPQkrAm-RgJ0W_zPyJMR013pZjOwPKlxKYbsW1G02Jbg2Vl1zatNWBm1MFYQYEOYyaNQkt32WktNdgixYg0Qdt3Q160mbfNz5c9USLVqvCsye0J2t9DZPK7WzadQCC4S7ehdmQkGd87IfD4XyKuZND_nE8Nz5nbgOLNfuIwR6QH7ksOHT9ur1JVKkzEkX8P40_7LXdarwraiBQ",
     "e": "AQAB",
     "use": "sig",
     "kid": "q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us",
     "qi": "t06uC_ML8E01gKSeFPH7LNFxpumuIaYBc_Enr10dB-wqGpYfs6B5yqf5SjlXg1K89Z3QZFcU9AdJW0SYtr9T-A7b3csxeWUW98hOwfXentP8vcSv3dXJI753f64tAZqz5Mgd6jh0D8i1Fvg6d7Hqm_a5cfd-DO80QkW9c8u8rmk",
     "dp": "L95hFWvBQVUb8WcavltWNxNMCR2m77aZcuLOHCFLV5TvxuHcgXsOPQRJk4852RlrbA5TYP5Qfx7EYD9acs5rGZQAV27s9s01DeGAC0yUj3lUmfDtp0M-BcZh7PcnX-O4DJfm4RqvhiIiOyXjSL8w-5330l6jr8lw6-6-yn8BTR8",
     "alg": "RS256",
     "dq": "lFS9ftClEcCxHn7Y-ZGkyDhK8ZFD9YF9ZVCUY5GqksRk5hdTylSlLNL7L_0sbqsrQGJFHe8aZL8nmBZ4n3utUrL2dlSBmo69jVARN7ddvep8gdktKlmsFChrfZ6SmdMIZZ0Su9FwyDEEwjKUVifOezwYHWmZ78dypHASTFJ-F08",
     "n": "jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q"
     }
     

   • Example public key

     {
     "kty": "RSA",
     "e": "AQAB",
     "use": "sig",
     "kid": "q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us",
     "alg": "RS256",
     "n": "jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q"
     }
     

Generate a signed JWT

1. Create a signed JWT with with a signing algorithm of RS256, RS384, or RS512 and header and payload information shown below.

   • Header

     {
      "alg": "RS256",
      "typ": "JWT"
     }
     

   • Payload

     {
      "iss": "{{appID}}",
      "sub": "{{appID}}",
      "exp": 1691085204,
      "aud": "https://auth.pingone.com/{{envID}}/as/token"
     }
     

2. Record the token returned successfully.

Use the JWT in a token request

For applications that set the tokenEndpointAuthMethod to PRIVATE_KEY_JWT, the token request requires the following two properties:

• client_assertion

  A JWT that contains a signed assertion with the application’s credentials. This is the JWT that you generated and signed with your private key.

• client_assertion_type

  A string that specifies the client assertion type. The value of this property must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

For more information about the token request, see Token.

In the PingOne application configuration, when the tokenEndpointAuthMethod property is set to PRIVATE_KEY_JWT, the configuration requires either the jwks property (specifying a JWKS string) or the jwksUrlproperty (specifying the location on a web server that hosts the JWKS string).

When using the jwksUrl property, the application configuration JSON looks like this. Note that the jwksUrl must be https://:

{
  ...
  "tokenEndpointAuthMethod": "PRIVATE_KEY_JWT",
  "jwksUrl": "https://{{pathToJwksString}}",
  ...
}

The application configuration JSON for the JWKS string in the jwks property must be formatted as one line with double quotes escaped:

{
  ...
  "tokenEndpointAuthMethod": "PRIVATE_KEY_JWT",
  "jwks": "{"jwks": "{ \"keys\": [ { \"kty\": \"RSA\", \"e\": \"AQAB\", \"use\": \"sig\", \"kid\": \"q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us\", \"alg\": \"RS256\", \"n\": \"jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q\" } ]}",
  ...
}

The following information describes the steps for generating the JWKS for use with "tokenEndpointAuthMethod": "PRIVATE_KEY_JWT".

Create the JWKS string

You will use the generated keys you created for your private key JWT (see Create a private key JWT) to generate a JWKS string object that can be used as the value in your PingOne application’s jwks property.

1. Copy the Public Key and wrap it like this:

   {
   "keys": [
     <Your public key>
    ]
   }
   

   Which looks like this:

   {
   "keys": [
      {
        "kty": "RSA",
        "e": "AQAB",
        "use": "sig",
        "kid": "q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us",
        "alg": "RS256",
        "n": "jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q"
      }
    ]
   }
   

2. The string needs to be reduced to one line and the double quotes escaped.

   The JSON for the PingOne application POST (or PUT) to create the application looks like:

   {
     ...
     "tokenEndpointAuthMethod": "PRIVATE_KEY_JWT",
     "jwks": "{\r\n  \"keys\": [\r\n    {\r\n        \"kty\": \"RSA\",\r\n        \"e\": \"AQAB\",\r\n        \"use\": \"sig\",\r\n        \"kid\": \"q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us\",\r\n        \"alg\": \"RS256\",\r\n        \"n\": \"jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q\"\r\n    }\r\n  ]\r\n}",
     ...
   }
   

Configure the JWKS URL

To use the jwksUrl property in the PingOne application's configuration, the JWKS string must be hosted on a web server, accessible to the internet (using https://). For testing purposes, the following code sample shows a simple node server file (running on a local web server) that hosts the JWKS string.

const https = require("https");
const host = 'localhost';
const port = 3000;

const requestListener = function (req, res) {
    res.setHeader("Content-Type", "application/json");
    res.writeHead(200);    

    const jwksString = "{\r\n  \"keys\": [\r\n    {\r\n        \"kty\": \"RSA\",\r\n        \"e\": \"AQAB\",\r\n        \"use\": \"sig\",\r\n        \"kid\": \"q3sWApYjHZQLmWMUdAIqZiVWSshDdau5eI4K_Bm65Us\",\r\n        \"alg\": \"RS256\",\r\n        \"n\": \"jWA_vDxg41NrYJdIiv3BcljMy7V15bMyOyK5aJov6FgUTE2Xm_B9SqJu55qmS3CxVhvYWSpRIZvhrgap19CE_VnrAc5pzwj2oSEmDRXXFSGmMjHAmfTXU66nDZVmhbtDIBkPU-h55RDZf6zIn3SPOrmWJYj0G5X2fMJfbUOpuROjH1aMqqGOxcT-dX-LA0dd94LrH4J-g1HFeGZqw-uyQO8l1g6fbQYVaNvnHtw9V7U7I684Ks-3sZcU-YhexNhiN53izIglhdVva9pjSTUk4BnmYtSlfyF6HzUYkvg3H1S0Y6LqzW8lOIw8SF-L6jQqkT2DPDwDbxzNoaNx8lIE0Q\"\r\n    }\r\n  ]\r\n}";

    res.end(jwksString);
};

const server = https.createServer(requestListener);
server.listen(port, host, () => {
    console.log(`Server is running on https://${host}:${port}`);
});

With the JWKS string in a known location, the application configuration JSON looks like this:

{
  ...
  "tokenEndpointAuthMethod": "PRIVATE_KEY_JWT",
  "jwksUrl": "jwksUrl": "{{pathToJwksString}}",
  ...
}

The external authentication API provides endpoints for performing end user authentication with PingOne supported external identity providers. End users are redirected immediately to the authentication initialization endpoint at the external authentication service. After users authenticate at the provider, they are redirected back to the external authentication service's authentication callback endpoint, where the external authentication API validates the token or assertion returned from the external identity provider.

External authentication data model