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:

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, in a browerless use cases such as with native mobile apps where the app wants 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 browserless 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": "{{envID}}/as",
  "iat": 1300819380,
  "exp": 1300819391

The JWT must be signed using the HS256 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.

Browserless flow for mobile clients

A browserless flow for mobile clients that 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 browserless 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.

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