Qodex.ai

Authorize (Transaction Approval)

GET {{authPath}}/{{envID}}/as/authorize?state={{state}}&response_type=token%20id_token&response_mode=pi.flow&scope=openid&request={{requestString}}&client_id={{clientID}}

PingOne supports transaction approval when strong authentication is required for elevated security for a high-value transaction, or high-risk resource or service. The sample shows the GET /{{envID}}/as/authorize operation, which includes the response_mode and request parameters in the authorization request.

The request property contains request parameters from the application. If the application's supportUnsignedRequestObject property value is set to false, the JWT must be signed using the HS256 algorithm and the app's client secret as the key. Using a JWT enables integrity protection of parameters that are required for risk based authentication or privacy and consent use cases.

The request property JWT should be constructed according to the following example:

JWT: "header" :
{
  "alg": "HS256",
  "typ": "JWT"
},
"body" : 
{
  "aud": "https://auth.pingone.com/{{envID}}/as",
  "iss": "{{appID}}",
  "pi.template": {
    "name": "{{templateName}}",
    "variant": "{{variantName}}",
    "variables": {
      "key1": "value1"
    }
  },
  "pi.clientContext": {
    "key2": "value2"
  }
}

Note: The request property specifies a JWT that enables OIDC/OAuth2 request parameters to be passed as a single, self-contained parameter. For details on how to construct the JWT, see Create a request property JWT. For information on pi.template see Notifications Templates. For information on pi.clientContext see Device Authentication.

ParameterDescription
client_idThe application's UUID.
requestA JWT that enables OIDC/OAuth2 request parameters to be passed as a single, self-contained parameter. If the application's supportUnsignedRequestObject property value is set to false, the JWT must be signed. 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 or voice message, push notification, or email message.
response_modeThe mechanism for returning authorization response parameters from the authorization endpoint. Options are query, fragment, form_post, and pi.flow. 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 more information about the query, fragment, and form_post options, see the ResponseModes section of the OAuth 2.0 Multiple Response Type Encoding Practices specification. For browserless use case information, see Browserless authentication flow options.
response_typeThe code or token type returned by an authorization request. Options are token, id_token, and code.
scopePermissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.
stateUsed to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter.

Request Params

KeyDatatypeRequiredDescription
statestring
response_typestring
response_modestring
scopestring
requeststring
client_idstring
promptstringOptional ( none
max_agenumberOptional - uses seconds
acr_valuesstringOptional - use Sign-on Policy names (space-delimited)

RESPONSES

status: OK

{"_links":{"otp.check":{"href":"https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/flows/0392192e-8616-4d70-af9d-10631b3fd2ca"},"device.select":{"href":"https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/flows/0392192e-8616-4d70-af9d-10631b3fd2ca"},"self":{"href":"https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/flows/0392192e-8616-4d70-af9d-10631b3fd2ca"},"signOnPage":{"href":"https://apps.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/signon/?flowId=0392192e-8616-4d70-af9d-10631b3fd2ca"}},"_embedded":{"devices":[{"id":"1237625c-12f9-4ab1-8656-351142b6c100","type":"SMS","status":"ACTIVE","phone":"*******01"}],"application":{"name":"WebAppWithMFA_1628117875"}},"id":"0392192e-8616-4d70-af9d-10631b3fd2ca","environment":{"id":"abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"},"resumeUrl":"https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/as/resume?flowId=0392192e-8616-4d70-af9d-10631b3fd2ca","status":"OTP_REQUIRED","createdAt":"2021-08-04T23:00:02.383Z","expiresAt":"2021-08-04T23:15:02.666Z","bypassAllowed":false,"selectedDevice":{"id":"1237625c-12f9-4ab1-8656-351142b6c100"}}