The authorization endpoint is used to interact with the end user and obtain an authorization grant. The sample shows the GET /{environmentId}/as/authorize operation, which includes the response_mode parameter to designate one of the following special authentication flow options:

To enable these flows, the authorize request uses the following properties as parameters in the request to determine the authorization processing flow:

Property Description
response_mode A string that specifies the mechanism for returning authorization response parameters from the authorization endpoint. This property specifies the pi.flow value to designate 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.
login_hint_token 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. Using a separate token instead of the login_hint parameter also means that this token can be signed by a client different from the authenticating client.
request A JWT that 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. Specifically:
  • Passing in the user agent’s original IP address when the PingOne platform is used behind a server side application that is functioning as an authentication gateway or PingFederate.
  • Passing in a purpose or usage description string that could be displayed to the user on the authentication UI prompt, SMS message, push notification, or email message.

To build the login_hint_token JWT, see Create a login_hint_token JWT.

To build the request JWT, see Create a request property JWT.

Browserless MFA flow example

Using both the login_hint_token and request properties, you can set up a browserless MFA flow that can evaluate a user’s IP address to determine whether an MFA action is required. In this use case, the authorize request looks like this:

https://auth.pingone.com/{{envId}}/as/authorize?acr_values=MFA-Only&response_type=token id_token&client_id={{clientId}}&response_mode=pi.flow&scope=openid profile email&state={{state}}&login_hint_token={{loginHintTokenJWT}}&request={{requestJWT}}

The acr_values property identifies an MFA sign-on policy name that includes the appropriate IP-based rules.

The login_hint_token property value is a JWT that includes the following claims:

{
"iss": "{{issuerApplicationId}}",
"aud": "https://auth.pingone.com/{{envId}}/as",
"sub": "{{authenticatedUserId}}"
}

The request property value is a JWT that includes the following claims:

{
"iss": "{{issuerApplicationId}}",
"aud": "https://auth.pingone.com/{{envId}}/as",
"pi.remoteIp": "{{ipAddress}}"
}

The request token passes in the user’s IP address securely.