PingOne Platform APIs

Redirect and non-redirect authentication flows

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.

Flows that redirect the browser to the custom authentication interface can set a specific login page URL on the application configuration using the loginPageUrl property. If this property is not set, the OIDC application includes a Ping-provided login page at https://{{apps domain}}/{{environmentID}}/signon/ or https://{{custom domain}}/signon/ in the Location header returned by an authorization request. The URL in each case includes the flowId parameter. If a custom domain is not set, the URL for the Ping-provided login page includes the environmentId parameter:

https://apps.pingone.com/03960928-f304-476c-858b-f2b51e5e058f/signon/?flowId=03de5b2a-aec8-4481-ae72-4e01f42bdff1

or with a custom domain,

https://example.com/signon/?flowId=0370bd50-0f2a-4749-afd4-195a63553372

If the loginPageUrl property is set (regardless of whether a custom domain is defined or not), the sign-on URL does not include /signon/ (unless added to the loginPageUrl value) but does include the environmentId and flowId parameters in the Location URL. For example, a loginPageUrl property set to https://login.acme.com/sign-on-here results in the following redirect URL to the login page:

https://login.acme.com/sign-on-here?environmentId=03960928-f304-476c-858b-f2b51e5e058f&flowId=0370bd50-0f2a-4749-afd4-195a63553372

If a PingOne authentication session exists and the sign-on policy does not specify that re-authentication is needed, a login page is not displayed (for either the Ping-provided or custom cases).

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.

A browser-based application that interacts with the authorization endpoint using either form_post or pi.flow must protect itself against Cross Site Scripting (XSS) and Cross Site Request Forgery (CSRF) vulnerabilities. If a user has already authenticated using the browser, a malicious script running within the browser context that makes an authorization request using form_post or pi.flow may receive the user’s access/id tokens directly in the response. To mitigate this risk, ensure your application follows these recommendations:

  1. Disable support for the OAuth 2.0 Implicit Grant Type.

  2. Choose a Token Endpoint Authentication Method other than NONE.

  3. Configure the application’s corsSettings.behavior property to ALLOW_SPECIFIC_ORIGINS and in the corsSettings.origins property only list your application’s origins. For more information, refer to Application Operations.

  4. Ensure that your application is written with security best practices to prevent script injection.

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, refer to 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}}

For more information about creating the login_hint_token or request token values, refer to Create a login_hint_token JWT and Create a request property JWT.

PingOne authorization with DaVinci flow policies

PingOne flows that specify a DaVinci flow policy 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). For DaVinci and PingOne configuration requirements, refer to PingOne Initiated Flows.

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.

response_mode response_type Supported option

omitted

code

query

omitted

id_token

fragment

omitted

token

fragment

omitted

id_token token

fragment

omitted

code id_token

fragment

omitted

code token

fragment

omitted

code id_token token

fragment

query

code

query

query

id_token

error

query

token

error

query

id_token token

error

query

code id_token

error

query

code token

error

query

code id_token token

error

fragment

code

fragment

fragment

id_token

fragment

fragment

token

fragment

fragment

id_token token

fragment

fragment

code id_token

fragment

fragment

code token

fragment

fragment

code id_token token

fragment

form_post

code

form_post

form_post

id_token

form_post

form_post

token

form_post

form_post

id_token token

form_post

form_post

code id_token

form_post

form_post

code token

form_post

form_post

code id_token token

form_post

pi.flow

pi.flow