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, 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": "https://auth.pingone.com/{{environmentId}}/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.