PingOne integrates with applications that use standards-compliant protocols by taking on the role of an OpenID Connect provider and OAuth 2 authorization server. In this capacity, PingOne provides the framework for connected applications to access protected HTTP resources. For more information about OpenID Connect and OAuth 2, see the OpenID Connect 1.0 spec and the OAuth 2.0 Authorization Framework RFC6749.

The PingOne authorization endpoint /{{envID}}/as/authorize is used to interact with the resource owner and obtain an authorization grant. For more information and additional examples, see Authorization and authentication by application type.

OpenID Connect/OAuth2 data model

Application access control conditions

You can configure OpenID Connect applications for access control by setting the accessControl property on the application. For more information about accessControl properties, see Application Operations. When accessControl properties are set for an application, the user must meet the requirements specified by these application properties to get a token. If the user attempts to authenticate and the grant_type is either authorization_code or implicit, then the application's accessControl conditions are evaluated to determine whether the user can be issued a token.

The token (or tokens) is minted if the user meets the application's access control conditions. If the conditions are not met, the token (or tokens) is not issued and an ACCESS_FAILED error is returned. If access is denied, a USER.ACCESS_DENIED event is published; otherwise, a USER.ACCESS_ALLOWED event is published.

For more information, see Control access to applications through roles and groups.

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Response codes

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.

• Use an authentication JWT for token fulfillment

  Describes how to map attributes from a source's authentication JWT to the PingOne generated token.

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": "{ \"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}}",
  ...
}

Token fulfillment in PingOne enables admins to map attributes from a source's authentication JWT to the PingOne generated token to improve interoperability with OIDC applications. When a PingOne application has a tokenEdnpointAuthMethod set to PRIVATE_KEY_JWT or CLIENT_SECRET_JWT, claims from these source authentication tokens can be mapped to PingOne tokens using the following expression variables:

• #root.context.requestData.clientAssertion.{{property}}

  Represents the value of a specified property from the payload of the authentication JWT presented by the application at PingOne's token endpoint.

• #root.context.requestData.clientAssertion

  Represents the payload of the authentication JWT presented by the application at PingOne's token endpoint.

• #root.context.requestData.clientAssertionHeader.{{property}}

  Represents the value of a specified property from the header of the authentication JWT presented by the application at PingOne's token endpoint.

• #root.context.requestData.clientAssertionHeader

  Represents the header of the authentication JWT presented by the application at PingOne's token endpoint.

• #root.context.requestData

  Represents the header and the payload of the authentication JWT presented by the application at PingOne's token endpoint.

• #root.context.appConfig.tokenEndpointAuthMethod

  Represents the token endpoint authentication method of the requesting application. The value is either PRIVATE_KEY_JWT, CLIENT_SECRET_JWT, or null if the application is not configured to use PRIVATE_KEY_JWT or CLIENT_SECRET_JWT.

In PingOne, the resource's attribute mapping endpoint supports these expressions as request body parameters. For example, you can create a resource attribute on a custom resource using the Create Resource Attribute endpoint: POST {{apiPath}}/environments/{{envID}}/resources/{{resourceID}}/attributes. This POST requires a name/value pair, and in the sample request body below, the value specifies a custom1 property, which is a claim from the source authentication JWT (client_assertion).

{
    "name": "clientAssertion_custom",
    "value": "${#root.context.requestData.clientAssertion.custom1}"
}

The claim represented by custom1 from the authentication JWT will be mapped to the PingOne JWT returned by the PingOne token request. If the custom1 claim in the JWT represents a nested JSON object, you can write your expression as #root.context.requestData.clientAssertion.custom1.x or #root.context.requestData.clientAssertion.custom1['x'] to access a nested property named x from the sample JWT below:

{
  "iss": "{{issID}}",
  "sub": "{{subID}}",
  "aud": "https://auth.pingone.com/{{envID}}/as/token",
  "jti": "a_0eDHMN...",
  "exp": 1736268635,
  "iat": 1736268335,
  "custom1": {
    "x": "xerox",
    "y": "yankee"
  }
}

Additional examples

Suppose you have a source authentication JWT with the following headers and claims:

{
  "alg": "RS512",
  "kid": "2DqNmmIHeJq-YrcR7K8Pjwi4KAI"
}.{
  "iss": "2cdb6843-338d-44f7-b8b9-90ffa28c555d",
  "sub": "2cdb6843-338d-44f7-b8b9-90ffa28c555d",
  "aud": "https://auth.pingone.com/{{envID}}/as/token",
  "jti": "vm7kRZz_AM3bHAVRdrKlMA",
  "exp": 1734550892,
  "iat": 1734550592
}

Include JWT claims

If you create a resource attribute mapping POST request using the #root.context.requestData.clientAssertion expression in the value property, the PingOne token endpoint will include the source JWT claims in the response:

{
  "alg": "RS256",
  "kid": "default"
}.{
  "client_id": "2cdb6843-338d-44f7-b8b9-90ffa28c555d",
  "iss": "https://auth.pingone.com/6991589d-87eb-47f4-9131-284cebe106b3/as",
  "jti": "0e428c3e-592b-4ec3-9684-505573e7a2d0",
  "iat": 1734550592,
  "exp": 1734554192,
  "aud": [
    "abc itu"
  ],
  "scope": "openid myOidc example",
  "sub": "1fc88a5e-a677-4df7-81ae-75df4f7839d2",
  "sid": "e506bd43-830d-46b3-8487-b80fd1dd7df9",
  "context_requestData_clientAssertion_customResource": {
    "clientAssertion": {
      "iss": "2cdb6843-338d-44f7-b8b9-90ffa28c555d",
      "sub": "2cdb6843-338d-44f7-b8b9-90ffa28c555d",
      "aud": "https://auth.pingone.com/{{envID}}/as/token",
      "jti": "vm7kRZz_AM3bHAVRdrKlMA",
      "exp": 1734550892,
      "iat": 1734550592
    }
  },
  "env": "{{envID}}",
  "org": "{{orgID}}"
}

The context_requestData_clientAssertion_customResource attribute in the PingOne token includes the claims that the authentication JWT presented at PingOne’s token endpoint.

Include JWT headers and claims

If you use the #root.context.requestData expression in the value property of your attribute mapping, the PingOne token request will include the source JWT's headers and claims in the response:

{
  "alg": "RS256",
  "kid": "default"
}.{
  "client_id": "2cdb6843-338d-44f7-b8b9-90ffa28c555d",
  "iss": "https://auth.pingone.com/6991589d-87eb-47f4-9131-284cebe106b3/as",
  "jti": "0e428c3e-592b-4ec3-9684-505573e7a2d0",
  "iat": 1734550592,
  "exp": 1734554192,
  "aud": [
    "abc itu"
  ],
  "scope": "openid myOidc example",
  "sub": "1fc88a5e-a677-4df7-81ae-75df4f7839d2",
  "sid": "e506bd43-830d-46b3-8487-b80fd1dd7df9",
  "context_requestData_customResource": {
    "clientAssertionHeader": {
      "alg": "RS512",
      "kid": "2DqNmmIHeJq-YrcR7K8Pjwi4KAI"
    },
    "clientAssertion": {
      "iss": "2cdb6843-338d-44f7-b8b9-90ffa28c555d",
      "sub": "2cdb6843-338d-44f7-b8b9-90ffa28c555d",
      "aud": "https://auth.pingone.com/{{envID}}/as/token",
      "jti": "vm7kRZz_AM3bHAVRdrKlMA",
      "exp": 1734550892,
      "iat": 1734550592
    }
  },
  "env": "{{envID}}",
  "org": "{{orgID}}"
}

The context_requestData_customResource attribute in the PingOne token includes the headers and claims that the authentication JWT presented at PingOne’s token endpoint.

The authorize endpoints support the following actions:

• The authorize endpoint /{{envID}}/as/authorize is used to interact with the end user and obtain an authorization grant. Note that PingOne supports both GET and POST operations for authorize requests. The supported parameters for an authorize request vary depending on the value of the response_type parameter (code, token, id_token or combinations of these three options).

• For non-redirect flows, such as with native mobile apps in which the app renders the end user interface, response_mode property value is set to pi.flow. This setting allows the app to authenticate using the PingOne flows API without needing to handle HTTP redirections. The pi.flow value is also used with transaction approval use cases in which strong authentication is required for elevated security for a high-value transaction, or high-risk resource or service.

• For applications having authorization_code or device_code grant types, and if the application's resource grant includes the offline_access scope, if offline_access is included in the scope parameter of the authorize request, a refresh token is included in the token response. If the offline_access socpe is omitted from the authorize request in this case, a refresh token is not included, even if the grant type allows it.

  If the client includes prompt=consent in a request with an authorization_code grant type, PingOne doesn't prompt for application consent. This limitation doesn't apply to requests with a device_code grant type, because the PingOne authentication policy service always prompts for application consent when requests use the device_code grant type.

• For applications having a refresh_token grant type, when the client includes offline_access in the scope parameter, and the request is using the authorization_code or device_code grant type, a refresh token is always included in the token response. See Application Resource Grants to add the refresh_token grant type to an application.

  If the application does not have a resource grant that includes offline_access in the scope parameter, a refresh token is always included in the token response for grant types that allow it.

Use Cases

• Configure a Simple Login
• Configure a PKCE authorization workflow
• Create an MFA Transaction Approval using SMS
• Use LOGIN and MFA Actions to Authenticate Users
• Configure a Progressive Profiling Sign-On Action
• Use LOGIN and AGREEMENT Actions to Authenticate Users
• Configure an MFA Only Flow Using a Login Hint Token
• Test an OAuth Connection using Identifier First Authentication

Related topics

Applications can use a pushed authorization request (PAR) to securely initiate authorization flows. A PAR allows applications to send their authorization requests directly to PingOne without going through the browser, which safeguards sensitive data from end-user devices.

With a PAR, an application can push an authorization request payload to PingOne with a direct back-channel request, which is a more secure method of sending sensitive data, such as personally identifiable information, than sending it with a browser on the front channel.

The POST /{{envID}}/as/par endpoint accepts the same request parameters as /{{envID}}/as/authorize, as well as any additional parameters needed for client authentication. It can accept signed and unsigned requests. Requests must be less than 1MB.

After PingOne validates the request and saves the payload, it returns the request_uri parameter as a reference to the payload. The response also indicates the lifetime of the request URI. The default lifetime is 60 seconds.

The application then uses the front channel to request an authorization code or token, sending the request_uri parameter to PingOne. PingOne uses the request URI to look up the request payload and continue the authorization flow. PingOne accepts a particular request URI only once.

For more information on the PAR specification, see RFC 9126.

The device authorization grant endpoints support the following actions for applications configured with the DEVICE_CODE grant type:

• The device authorization endpoint /{{envID}}/as/device_authorization starts an action to return an activation code to the end user. The endpoint response returns a device code, a user code, and a verification URI. The supported parameters for the endpoint request are the client_id parameter and an optional scope parameter.

• The start flow endpoints /{{envID}}/device/{{appIdentifier}} or /{{envID}}/device in which the appIdentifier variable represents one of either the application ID (clientId or applicationId) or a short secondary application identifier (devicePathId configured per app) that is used only with the /device endpoint.

• The token endpoint /{{envID}}/as/token returns the tokens issued for the device.

Use Cases

• Configure Device Authorization Grant Flow

Device authorization grant data model

Related topics

The token endpoints support the following actions:

• The token endpoint /{{envID}}/as/token is used by the client to obtain an access token by presenting its authorization grant. Note that authentication requirements to this endpoint are configured by the application's tokenEndpointAuthMethod property. For information about the application's tokenEndpointAuthMethod property, see the "Applications OIDC settings data model" table in Application Operations.

• The token introspection endpoint /{{envID}}/as/introspect returns the active state of an OAuth 2.0 token and the claims specified in RFC 7662 Section 2.2. The request requires the token parameter, which is the token string.

• The token revocation endpoint {{envID}}/as/revoke revokes the token specified in the request. Note that this operation does not apply to the tokens issued for the PingOne API resource.

Use Cases

• Get a token for custom resource access
• Add a custom claim to an access token
• Use LOGIN and MFA Actions to Authenticate Users
• Exchange a Refresh Token
• Configure CLIENT_SECRET_JWT as the token auth method
• Get an ID Token
• Configure an MFA-Only Flow Using a Login Hint Token

Related topics

The SAML endpoints are used by SAML applications to initiate sign-on and signoff operations. The SAML service implements functions to initiate SAML 2.0 single sign-on and single logout authentication flows.

Use Cases

• Test a SAML application connection
• SAML Sign-On

SAML 2.0 protocol

The SAML protocol allows clients to obtain a requestor’s authentication state. SAML 2.0 uses security tokens, which contain assertions about the requestor, to pass authentication and authorization information about the requestor between the identity provider and the resource provider.

SAML SSO authentication requests

A SAML SSO authentication request uses the following authentication flow:

1. The client (browser) initiates a login action to access a protected resource.
2. The identity provider issues an <AuthnRequest> message to be delivered by the user agent to the SAML service endpoint using either HTTP Redirect or HTTP POST.
3. The SAML service validates the request and creates an authentication flow with the flow orchestration service.
4. The SAML service indicates user interaction is required to perform the authentication flow.
5. The browser is redirected to the PingOne hosted authentication UI or the per application configured URL of a custom UI, passing in the environmentId and flowSessionId query parameters. The authentication UI uses flow orchestration and action services endpoints to complete the authentication flow. The authentication API checks on every call to ensure that the session token cookie contains the current token for the session associated with the flow. On successful completion of the flow, a new session token is generated for the session and set in the cookie.
6. The browser is redirected to the resume endpoint of the SAML service.
7. The SAML service retrieves and deletes the authentication flow from the flow orchestration service.
8. The SAML service generates the appropriate tokens and issues a <Response> message delivered by the user agent to the identity provider using HTTP POST.

The following is a sample SAML assertion generated for an authentication <AuthnRequest> request:

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="identifier_1"
    Version="2.0"
    IssueInstant="2004-12-05T09:21:59">
    <saml:Issuer>https://sp.example.com/SAML2</saml:Issuer>
  </samlp:AuthnRequest>

Request model

The following is a sample SAML assertion response:

<samlp:Response
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="identifier_2"
    InResponseTo="identifier_1"
    Version="2.0"
    IssueInstant="2004-12-05T09:22:05"
    Destination="https://sp.example.com/SAML2/SSO/POST">
    <saml:Issuer>https://auth.pingone.com/{{envID}}</saml:Issuer>
    <samlp:Status>
      <samlp:StatusCode
        Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:Assertion
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
      ID="identifier_4"
      Version="2.0"
      IssueInstant="2004-12-05T09:22:05">
      <saml:Issuer>https://auth.pingone.com/{{envID}}</saml:Issuer>
      <!-- a POSTed assertion MUST be signed -->
      <ds:Signature
        xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
      <saml:Subject>
        <saml:NameID
          Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
          3f7b3dcf-1674-4ecd-92c8-1544f346baf8
        </saml:NameID>
        <saml:SubjectConfirmation
          Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
          <saml:SubjectConfirmationData
            InResponseTo="identifier_1"
            Recipient="https://sp.example.com/SAML2/SSO/POST"
            NotOnOrAfter="2004-12-05T09:27:05"/>
        </saml:SubjectConfirmation>
      </saml:Subject>
      <saml:Conditions
        NotBefore="2004-12-05T09:17:05"
        NotOnOrAfter="2004-12-05T09:27:05">
        <saml:AudienceRestriction>
          <saml:Audience>https://sp.example.com/SAML2</saml:Audience>
        </saml:AudienceRestriction>
      </saml:Conditions>
      <saml:AuthnStatement
        AuthnInstant="2004-12-05T09:22:00"
        SessionIndex="identifier_3">
        <saml:AuthnContext>
          <saml:AuthnContextClassRef>
            urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
         </saml:AuthnContextClassRef>
        </saml:AuthnContext>
      </saml:AuthnStatement>
    </saml:Assertion>
  </samlp:Response>

IdP-Initiated SSO

IdP-initiated SSO allows users to authenticate through their identity provider, which then issues and signs SAML assertions to service providers. This allows users to access multiple applications and services with a single authentication.

IdP-Initiated SSO uses the following flow:

1. A user signs on to their system with a username and password and is presented with an application catalog that displays icons representing the web-based applications and services they can access.
2. The user clicks an icon to access one of those applications or services.
3. The IdP creates and signs an SAML assertion that includes information about the user’s identity, along with any other attribute information that the IdP and SP agreed to share to authenticate users.
4. The IdP either sends the assertion to the SP through a browser or sends a reference to the assertion that the SP can use to securely retrieve the assertion.
5. The SP validates the signature to ensure that the SAML assertion really came from its trusted IdP and that none of the values in the assertion have been modified. It also extracts the identity, attribute, and authorization information it needs to determine whether access should be granted and which privileges the user will have.
6. Users access the application or service.

IdP-Initiated SSO has the following benefits:

• The user gains access to catalog of applications and services with a single authentication.
• The authentication flow is more secure because user credentials are never transmitted between IdP and SP.
• The authentication flow is simpler because it eliminates a redirect step from SP to IdP.

You can start the IdP-Initiated SSO authentication session using the Get Identity Provider Initiated SSO request.

SAML SLO logout requests

A SAML single logout (SLO) operation uses the following flow:

1. The user initiates logout.
2. The session participant initiates single logout by sending a <LogoutRequest> message to the identity provider that sent the corresponding <AuthnRequest> authentication assertion.
3. The SAML service validates the request. It then calls the end session endpoint of the flow orchestration service and passes through the cookie header. The flow orchestration service deletes the session identified by the session cookie and includes a Set-Cookie in the response to immediately expire the session cookie.
4. The identity provider uses the contents of the <LogoutRequest> message to determine the session(s) being terminated.
5. The identity provider issues a <LogoutResponse> message to the original requesting session participant.

DaVinci flows with SAML applications

The following workflow outlines the interaction between PingOne applications and DaVinci flows and flow policies.

1. PingOne applications support a configuration option to assign DaVinci flow policies to the application. For information on designating a DaVinci flow as a PingOne flow, see PingOne Initiated Flows.

2. The SAML SSO service retrieves the application configuration data. Based on the configuration, the application can use either a PingOne sign-on policy or a DaVinci flow policy to determine the sign-on workflow. To assign DaVinci flow policies to applications, see Application Flow Policy Assignments.

3. For DaVinci flow policy use cases, the DaVinci widget renders the sign-on flow page. For more information about DaVinci widgets, see Launching a flow with the widget in the PingOne admin documentation.

4. The DaVinci widget manages the flow, and after the flow completes, the PingOne SSO Connector creates a session and passes control back to the protocol service.

5. The SAML SSO service processes the response, performs attribute mapping using user attributes from the PingOne directory, creates a SAMLResponse, and sends it to the SAML application.

6. The application continues its normal flow, calling the PingOne token endpoint to obtain the tokens.

SAML data model

Application access control conditions

You can configure SAML applications for access control by setting the accessControl properties on the application. For more information about accessControl properties, see Application Operations. When accessControl properties are set for an application, the user must meet the requirements specified by these application properties. If the user attempts to authenticate, then the application's accessControl conditions are evaluated before creating an assertion.

An assertion is created if the user meets the the application's access control conditions. If the conditions are not met, then an authorization failed error is returned with the top level code urn:oasis:names:tc:SAML:2.0:status:Responder and the second level code urn:oasis:names:tc:SAML:2.0:status:RequestDenied. If access is denied, a USER.ACCESS_DENIED event is published; otherwise, a USER.ACCESS_ALLOWED event is published.

For more information, see Control access to applications through roles and groups.

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Response codes

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.

Use Cases

• Sign-on using an External Identity Provider

External authentication data model

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Response codes

The flow endpoint is used to interact with the user in a sign-on workflow. Flow endpoint operations are used only to implement custom authentication UIs. OIDC/OAuth 2 and SAML requests initiate the flow and redirect the browser to the custom authentication UI (which is configured in the application through the application's loginPageUrl property).

Common sign-on actions

Login actions

The flow endpoint can initiate login actions that specify the operations required to authenticate with a username and password.

Multi-factor authentication actions

The flow endpoint can also initiate multi-factor authentication (MFA) actions that specify the operations required to complete authentication using a registered user device and a one-time password (OTP).

Identity first actions

The flow can initiate a discovery action used to identify the user by username and determine the applicable authentication methods for this user.

Progressive profiling actions

Progressive profiling actions prompt users to provide additional data at sign on. This action type does not authenticate users. It is used only to obtain additional profile data.

Agreement actions

Agreement actions enforce user consent to an agreement at sign on. This action type does not authenticate users. It is used only to obtain user consent to a terms of service agreement.

Identity provider actions

An action that bypasses the PingOne sign-on prompt and immediately redirects the user to an external identity provider's sign-on workflow to authenticate.

Use Cases

• Use LOGIN and MFA Actions to Authenticate Users
• Add a user through a registration flow
• Configure a PKCE authorization workflow
• Configure a Progressive Profiling Sign-On Action
• Use LOGIN and AGREEMENT Actions to Authenticate Users
• Configure an MFA Only Flow Using a Login Hint Token
• Create an MFA Transaction Approval using SMS

Flow status

In a sign-on workflow, the flow's status property value returned by the last action identifies the appropriate next action in the authentication process. For example, if an application uses the LOGIN sign-on policy, when a user initiates sign-on and starts the authentication flow, the response returned by the flow shows a status value that specifies the next required step to complete this flow successfully. For the LOGIN sign-on policy, the next action prompts the user to enter a username and password, as indicated by the USERNAME_PASSWORD_REQUIRED value in the status property.

"status" : "USERNAME_PASSWORD_REQUIRED"

The response data includes a link to the required action, which in this case is the usernamePassword.check:

{
  "_links" : {
    "self" : {
      "href" : "https://auth.pingone.com/{{envID}}/flows/{{flowID}}"
    },
    "session.reset" : {
      "href" : "https://auth.pingone.com/{{envID}}/flows/{{flowID}}"
    },
    "usernamePassword.check" : {
      "href" : "https://auth.pingone.com/{{envID}}/flows/{{flowID}}"
    }
  },

After the user submits a username and password, the flow calls the usernamePassword.check action to verify the username and password.

For more information about flow actions, see Flow API Actions.

Flow status values

An authentication flow can return one of the following status values in response to a sign-on action:

Flow status data model and embedded resources

The following sections show the parameters required by the flow status. In addition, the following links and embedded resources are returned in the flow response for the given flow status.

USERNAME_PASSWORD_REQUIRED

SIGN_ON_REQUIRED

PASSWORD_REQUIRED

PASSWORD_EXPIRED

MUST_CHANGE_PASSWORD

RECOVERY_CODE_REQUIRED

VERIFICATION_CODE_REQUIRED

DEVICE_SELECTION_REQUIRED

OTP_REQUIRED

PUSH_CONFIRMATION_REQUIRED

PUSH_CONFIRMATION_TIMED_OUT

ACCOUNT_LINKING_REQUIRED

ACCOUNT_CONFIRMATION_REQUIRED

EXTERNAL_AUTHENTICATION_REQUIRED

PROFILE_DATA_REQUIRED

ASSERTION_REQUIRED

AGREEMENT_CONSENT_REQUIRED

DAG_USER_CODE_REQUIRED

DAG_CONSENT_REQUIRED

Related topics

The GET /{{envID}}/flows/{{flowID}} operation retrieves the flow specified by the flowID in the request URL. For more information about this flow action, see Get a flow.

Flow API actions

The flow endpoint operation, POST /{{envID}}/flows/{{flowID}}, supports several flow actions that are specified by the custom media type provided in the HTTP Content-Type request header. The following table lists the PingOne custom media types and their associated authentication flow actions:

Flows common response data model

These common properties are returned with the flow response.

These common links are returned with the flow response.

These common embedded resources are returned with the flow response:

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Response codes

Related topics

The forgot password endpoints provide the flow actions to recover a user's forgotten password. These flow actions allow the user to recover the account and set a new password.

The registration and verification endpoints provide flow actions for the following authentication workflows:

• Register new users.

• Verify the newly registered user account.

• Update user profiles.

• Confirm user account information received from an external identity provider.

• Prompt users to consent to (or reject) an agreement.

Related topics

The device authorization grant endpoints provide the flow actions to verify a user's device user code and accept a consent agreement for the device. These flow actions address the flow states generated in a device code authentication flow.

The flows endpoint supports operations to accept administrator invitations sent to users.

Response codes

The flow execution APIs called to initiate a DaVinci flow depend on whether the flow is a PingOne flow or a DaVinci (non-PingOne) flow. PingOne flows use the PingOne authorize endpoint /as/authorize to initiate the authentication workflow. DaVinci flows use the /policy/{{davinciFlowPolicyID}}/start endpoint to initiate the flow.

The PingOne initiated flows provide two configuration options that determine the data structure of the responses:

• Default flow execution

  The authorize request and flow endpoints return concise and trimmed JSON responses with only functional details. Flow execution results in a valid session.

• Detailed responses in flow execution

  The authorize request and the flow endpoints return verbose responses that include properties such as the frontend HTML and scripts to build the interface forms. Like the scenario above, the flow execution results in a valid session.

  See PingOne Initiated Flows for configuration details.

DaVinci native flows do not use the PingOne authorize request to start the flow.

• Direct flow executions using DaVinci APIs

  Direct flow executions use the DaVinci /start request to initiate the flow. This scenario is often used for flows that do not require user interactive steps. It supports use cases where you need flexibility in sending custom JSON responses to the client, whether flow execution succeeds or fails. For these flows, successful flow execution may not require obtaining a valid session as a result.

  See DaVinci Direct Flow Executions for configuration details.

When you use a PingOne authorize request to initiate DaVinci flow execution, you can choose between the following configuration options:

• Default flow execution

  This scenario uses a PingOne OIDC application and a DaVinci flow designated as a PingOne flow. Flow execution is initiated by a PingOne authorize request (POST {{authPath}}/{{envID}}/as/authorize) that specifies pi.flow as the response mode and the X-Requested-With HTTP header set to ping-sdk. The flow endpoints return concise and trimmed JSON responses with only functional details. Flow execution results in a valid session. (Note: This configuration supports using the same flow for web-based user interactive and headless flow execution.)

  See Default Approach for configuration details.

• Detailed responses in flow execution

  This scenario has similar characteristics to the one above. Flow execution is initiated by a PingOne authorize request (POST {{authPath}}/{{envID}}/as/authorize) that specifies pi.flow as the response mode. However, in this scenario, it omits the X-Requested-With HTTP header from the PingOne authorize request. The flow endpoints return verbose responses that include properties such as the frontend HTML and scripts to build the interface forms. Like the scenario above, the flow execution results in a valid session, and supports user interactive and headless flow execution.

  See Detailed Responses for configuration details.

PingOne flows use the PingOne authorize endpoint to start the flow. The authorize request must include the response_mode property set to pi.flow, which tells the authorization server to return a 200 OK response with a payload that can be either verbose (HTML and scripts to render the sign-on forms) or minimal (concise JSON responses that show the data properties and their values). Configuring your responses to return JSON gives you the flexibility to parse the response data, collect the information you need, and process it to suit your workflow.

To return JSON, the authorize request and every subsequent flow action request must include the X-Requested-With HTTP header with the value set to ping-sdk.

For example, the PingOne authorize request with X-Requested-With set to ping-sdk returns the following JSON response:

{
    "interactionId": "0964a6a0...",
    "connectorId": "api",
    "interactionToken": "e578ecc5c0f1b...",
    "success": true,
    "startUiSubFlow": true,
    "_links": {
        "next": {
            "href": "https://auth.pingone.asia/{{envID}}/davinci/connections/{{connectionInstanceID}}/capabilities/customHTMLTemplate"
        }
    },
    "eventName": "continue",
    "isResponseCompatibleWithMobileAndWebSdks": true,
    "id": "65u7m8cm28",
    "companyId": "424d6ac2...",
    "flowId": "1041e80...",
    "connectionId": "867ed4...",
    "capabilityName": "customHTMLTemplate",
    "formData": {
        "value": {
            "username": "",
            "password": ""
        }
    },
    "form": {
        "name": "Sign On Form",
        "description": "Prompt for username and password",
        "category": "CUSTOM_HTML",
        "components": {
            "fields": [
                {
                    "type": "TEXT",
                    "key": "username",
                    "label": "Username"
                },
                {
                    "type": "PASSWORD",
                    "key": "password",
                    "label": "Password"
                },
                {
                    "type": "SUBMIT_BUTTON",
                    "label": "Sign On",
                    "key": "SIGNON"
                },
                {
                    "type": "FLOW_BUTTON",
                    "label": "No account? Register now!",
                    "key": "REGISTER"
                },
                {
                    "type": "FLOW_BUTTON",
                    "label": "Having trouble signing on?",
                    "key": "TROUBLE"
                }
            ]
        }
    }
}

Use cases

• DaVinci Flow Execution Sign-on
• DaVinci Flow Execution Registration

DaVinci and PingOne configuration requirements

In DaVinci, you must configure your application, the flow, and the flow policy to meet the requirements below:

• A DaVinci application.

• A DaVinci flow designated as a PingOne flow.

• A DaVinci flow policy that includes the PingOne flow.

• A PingOne OIDC application that is associated with the DaVinci flow policy.

Flow execution

To execute a PingOne flow using APIs and receive JSON responses (instead of the usual HTML responses returned by DaVinci endpoints), follow these steps:

Step 1: Initiate the flow through a PingOne authorize request

1. Use the PingOne /as/authorize OIDC endpoint to initiate authorization.

2. In the authorize request, set the response_mode property value to pi.flow. The pi.flow value specifies a non-redirect flow where the redirect_uri parameter is not required and authorization response parameters are encoded as a JSON object and returned directly to the client.

3. Set the client_id (the PingOne application client ID mapped to the DaVinci flow policy), the response_type, and scopes properties for the authorize request. For information about PingOne authorize endpoint properties, see Authorization.

4. Add the X-Requested-With HTTP header and set the value to ping-sdk. The JSON response from the authorization server returns a next link that provides the request URL to proceed to the next step of the flow.

Step 2: Execute the next flow action

1. Use the next link returned in the response (example shown below) to execute subsequent steps of the flow. For information about building the next link's request body, see DaVinci Flow Capabilities.

"_links": {
        "next": {
            "href": "{{authPath}}/{{envID}}/davinci/connections/{{connectionInstanceID}}/capabilities/{{capabilityName}}"
        }
    },

2. Add the X-Requested-With HTTP header to each next request, and set its value to ping-sdk to ensure that the response returns JSON.

Step 3: Complete the flow

1. On successful flow completion, the response includes the ST-Cookie and ST-NO-SS session cookies in the response headers to indicate that a session has been established.

2. The response returns the returnSuccessResponseRedirect capability and the following JSON structure to PingOne:

{
  "environment" : {
    "id" : "6baead75..."
  },
  "session" : {
    "id" : "8e918b54..."
  },
  "authorizeResponse" : {
    "access_token" : "eyJraWQiOiI3YT...",
    "id_token" : "eyJraWQiOiI3YTVh...",
    "token_type" : "Bearer",
    "expires_in" : 3600,
    "scope" : "openid profile"
  },
  "status" : "COMPLETED"
}

DaVinci flow capabilities data model properties

PingOne flows use the PingOne authorize endpoint to start the flow. The authorize request must include the response_mode property set to pi.flow, which tells the authorization server to return a 200 OK response with a payload that can be either verbose (HTML and scripts to render the sign-on forms) or minimal (concise JSON responses that show the data properties and their values). Configuring your responses to return HTML provides the frontend HTML you need to create the sign-on interface. It is the most direct way to render the interactive UI forms to collect user input.

To return HTML, the authorize request sets the response_mode property to pi.flow, but it omits the X-Requested-With HTTP header.

For example, the PingOne authorize request configured without the X-Requested-With HTTP header returns the following response:

{
  "id" : "howu8n9hsc",
  "companyId" : "499a5cea55...",
  "flowId" : "56cb88...",
  "connectionId" : "867ed43...",
  "capabilityName" : "customHTMLTemplate",
  "screen" : {
    "name" : "HTTP",
    "properties" : {
      "sktemplate" : {
        "type" : "string",
        "displayName" : "Template",
        "createdDate" : 1694542156374,
        "customerId" : "ecb9bf...",
        "companyId" : "singularkey"
      },
      "customHTML" : {
        "type" : "string",
        "displayName" : "HTML Template",
        "viewToggle" : true,
        "largePayload" : true,
        "value" : "<div class=\"app-container\" ..."
      },
      "validationRules" : {
        "type" : "object",
        "displayName" : "Form validation rules",
        "info" : "Rules to check to validate form inputs",
        "preferredControlType" : "validationRules"
      },
      "customCSS" : {
        "type" : "string",
        "displayName" : "CSS",
        "language" : "css",
        "maximizeToggle" : true,
        "largePayload" : true
      },
      "customScript" : {
        "type" : "string",
        "displayName" : "Script",
        "language" : "javascript",
        "maximizeToggle" : true,
        "info" : "Write custom JavaScript"."
      },
      "inputSchema" : {
        ...
      },
      "outputSchema" : {
        ...
      },
      "formFieldsList" : {
        "type" : "array",
        "constructType" : "formFieldsList",
        "displayName" : "Output Fields List",
        "preferredControlType" : "formFieldsList",
        "hideLabel" : false,
        "value" : [ {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "username",
          "displayName" : "Username",
          "hashedVisibility" : false
        }, {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "password",
          "displayName" : "Password",
          "hashedVisibility" : true
        }, {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "buttonValue"
        } ]
      },
      "challenge" : {
        "type" : "string",
        "displayName" : "Challenge",
        "preferredControlType" : "textField",
        "enableParameters" : true
      },
      "button" : {
        "constructType" : "button",
        "displayName" : "Submit",
        "preferredControlType" : "button",
        "css" : {
          "backgroundColor" : "#1CAB42",
          "color" : "#ffffff"
        },
        "onClick" : {
          "constructType" : "skEvent",
          "eventName" : "continue",
          "eventType" : "post",
          "postProcess" : { }
        }
      },
      "showFooter" : {
        "value" : true
      },
      "returnRequestParameters" : {
        "value" : true
      },
      "messageTitle" : {
        "value" : "Information"
      },
      "message" : {
        "value" : ""
      },
      "showPoweredBy" : {
        "value" : false
      },
      "showContinueButton" : {
        "value" : false
      },
      "httpMethod" : {
        "value" : "GET"
      },
      "httpBody" : {
        "value" : "none"
      },
      "raw" : {
        "value" : ""
      },
      "signResponse" : {
        "value" : false
      },
      "additionalFieldsName" : {
        "value" : "additionalProperties"
      },
      "unsafeIgnoreTLSErrors" : {
        "value" : false
      },
      "delayTime" : {
        "value" : 50
      },
      "returnSuccess" : {
        "value" : true
      },
      "keepOutputIfNotValid" : {
        "value" : false
      },
      "fieldValidation" : {
        "value" : false
      },
      "outboundMtlsKey" : {
        "value" : "none"
      },
      "nodeTitle" : {
        "value" : "Username/Password Form"
      },
      "isLinkStyleSheetSupportEnabled" : {
        "value" : false
      }
    },
    "userViews" : [ {
      "screenTemplateName" : "CustomHTMLTemplate",
      "items" : [ {
        "propertyName" : "sktemplate"
      }, {
        "propertyName" : "customHTML"
      }, {
        "propertyName" : "validationRules"
      }, {
        "propertyName" : "customCSS"
      }, {
        "propertyName" : "customScript"
      }, {
        "propertyName" : "inputSchema"
      }, {
        "propertyName" : "outputSchema"
      }, {
        "propertyName" : "formFieldsList"
      }, {
        "propertyName" : "challenge"
      }, {
        "propertyName" : "button"
      } ]
    } ],
    "metadata" : {
      "colors" : {
        "canvas" : "#AFD5FF",
        "canvasText" : "#253746",
        "dark" : "#2E5EA6"
      },
      "logos" : {
        "canvas" : {
          "imageFileName" : "http.svg"
        }
      },
      "type" : "core",
      "vendor" : ""
    }
  },
  "interactionId" : "0344195d...7",
  "interactionToken" : "26bb08a75...",
  "skProxyApiEnvironmentId" : "us-west-2",
  "_links" : {
    "self" : {
      "href" : "https://auth.pingone.com/{{envID}}/davinci/policy/{{davinciFlowPolicyID}}/start"
    }
  }
}

Use cases

• Davinci Flow Execution Detailed Responses

DaVinci and PingOne configuration requirements

In DaVinci, you must configure your application, the flow, and the flow policy to meet the requirements below:

• A DaVinci application.

• A DaVinci flow designated as a PingOne flow.

• A DaVinci flow policy that includes the PingOne flow.

• A PingOne OIDC application that is associated with the DaVinci flow policy.

Flow execution

To execute a PingOne flow using APIs and receive verbose responses, follow these steps:

Step 1: Initiate the flow through a PingOne authorize request

1. Use the PingOne /as/authorize OIDC endpoint to initiate authorization.

2. In the authorize request, set the response_mode property value to pi.flow. The pi.flow value specifies a non-redirect flow where the redirect_uri parameter is not required and authorization response data is returned directly to the client.

3. Set the client_id (the PingOne application client ID mapped to the DaVinci flow policy), the response_type, and scopes properties for the authorize request. For information about PingOne authorize endpoint properties, see Authorization.

Step 2: Execute the next flow action

1. Use the resource link returned in the response (example shown below) to execute subsequent steps of the flow.

"_links": {
            "href": "{{authPath}}/{{envID}}/davinci/connections/{{connectionInstanceID}}/capabilities/{{capabilityName}}"
    },

Step 3: Complete the flow

1. On successful flow completion, the response includes the ST-Cookie and ST-NO-SS session cookies in the response headers to indicate that a session has been established.

2. The response returns the returnSuccessResponseRedirect capability and the following JSON structure to PingOne:

{
  "environment" : {
    "id" : "6baead75..."
  },
  "session" : {
    "id" : "8e918b54..."
  },
  "authorizeResponse" : {
    "access_token" : "eyJraWQiOiI3YT...",
    "id_token" : "eyJraWQiOiI3YTVh...",
    "token_type" : "Bearer",
    "expires_in" : 3600,
    "scope" : "openid profile"
  },
  "status" : "COMPLETED"
}

DaVinci flow capabilities data model properties

DaVinci flows use the /start endpoint to initiate a non-PingOne flow that will return HTML in the response. You can integrate a non-PingOne flow in the following ways:

• A redirect through PingOne. This method uses a call to a PingOne application to launch a flow with a redirect.

• A redirect through PingOne using DaVinci as an external identity provider (IdP). This method uses a call to a PingOne application to launch a flow with a redirect using an external IdP configuration.

• The widget. This method launches a flow inside of a widget on the current page.

• An API call. This method launches a flow using an API call.

For more information, see Integrating Flows into Applications in the PingOne DaVinci guide.

The /start endpoint initiates the flow (or flows) that are included in the flow policy specified by your DaVinci flow policy ID in the request URL. However, before you can initiate a flow policy, you must complete the following tasks:

1. Create a DaVinci application.

2. Create a flow.

3. Create a flow policy on the DaVinci application that specifies the flow you created in Step 2.

For more information, see Creating an application, How to create a flow, and Configuring a flow policy.

The /start API initiates a flow policy associated with an application, depending on the policy ID passed in with the request.

When you use the widget method to integrate DaVinci flow policies into your application, the /start request uses the endpoint from the auth.pingone.com resource server: The POST {{authPath}}/{{envID}}/policy/{{davinciFlowPolicyID}}/start.

For widget integration use cases, the code for the widget is embedded in the application's web page. In that scenario, the /start request should not use the application's API Key for security reasons. The application's API Key should be treated like a confidential secret; it cannot be exposed in a public web page. Instead, the POST {{authPath}}/{{envID}}/policy/{{davinciFlowPolicyID}}/start request uses a DaVinci SDK Token to authenticate the request and initiate the flow specified by the flow policy.

For more information about the widget application integration method, see Launching a flow with the widget in the PingOne admin documentation.

When you use the API method to integrate DaVinci flow policies into your application, the /start request uses the endpoint from the orchestrate-api.pingone.com resource server: POST {{orchestratePath}}/v1/company/{{companyID}}/policy/{{davinciFlowPolicyID}}/start.

For API integration use cases, this method is used for headless flow execution in which no end user is involved. This workflow can pass in the application's API Key directly because it should be protected from public exposure.

For more information about the API application integration method, see Launching a flow with an API call in the PingOne admin documentation.

For sample requests and responses that use the POST {{orchestratePath}}/v1/company/{{companyID}}/policy/{{davinciFlowPolicyID}}/start endpoint, see Create Start Company Flow Policy.

Flows can receive input parameters when invoked. It is good practice to configure the flow to validate input provided by users. Associating an input schema with the flow achieves input validation to ensure that the flow only allows input that meets your data criteria.

The following sample shows the request body for a /start request that uses input schema values in a user profile update flow. If input schema properties are designated as required, the flow invocation needs to pass in the required parameters to start the flow.

{
    "hostname": "bxhealth.devops.com",
    "dn": "uid=testpatient,ou=People,dc=bxhealth,dc=org",
    "modifications": [
        {
            "attributeName": "givenName",
            "modificationType": "set",
            "values": [
                "PatientFirst"
            ]
        },
        {
            "attributeName": "sn",
            "modificationType": "set",
            "values": [
                "PatientLast"
            ]
        }
    ]
}