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. The request URL includes the response_type parameter with a value of code, which designates that this authorization request, if successful, returns an authorization code that is exchanged for an access token.

For a Proof Key for Code Exchange (PKCE) authorization request, the /{environmentId}/as/authorize request must include the code_challenge parameter. The code_challenge_method parameter is required if the application’s pkceEnforcement property is set to S256_REQUIRED. Otherwise, it is optional.

The request parameter can be optionally signed with the application secret. The JWT should be constructed according to the following example:

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

Supported parameters for an authorization request with a code grant are:

Property Description
acr_values A string that designates the names of the sign-on policies that are included in the authorization flow request. Options can include the PingOne predefined sign-on policies, Single_Factor and Multi_Factor, or any custom defined sign-on policy names. Sign-on policy names should be listed in order of preference, and they must be assigned to the application.
client_id A string that specifies the application’s UUID. This is a required property.
code_challenge A string that is computed from the code_verifier that is used in a Proof Key for Code Exchange (PKCE) authorization request. The length and character set requirements for the code_challenge string are documented in Section 4.1 of RFC7636. The computation for the code_challenge string is documented in Section 4.2 of RFC7636.
code_challenge_method A string that specifies the computation logic used to generate the code_challenge string. The token endpoint uses this method to verify the code_verifier for PKCE authorization requests. Options are: plain and S256.
login_hint A string that specifies a login identifier to pre-fill the Username field of the sign-on screen. The string can be the UUID of an existing user in the environment, which results in the look-up of the user’s username property, or it can be another string used to pre-fill the sign-on screen. The Username field of the sign-on screen does not pre-fill if (1) no string is provided as a hint, and (2) the OpenID Connect scope openid is not specified. In the flow response, if the login_hint value is a username, the value is returned in the flow response’s identifier attribute. If the login_hint is a UUID, and the look-up finds a user, the username value is returned in the identifier attribute. If a user is not found, the UUID is returned in the flow response’s identifier attribute.
mobileRequest An optional parameter used by PingID to manage devices.
max_age A string that specifies the maximum amount of time allowed (in seconds) since the user last authenticated. If the max_age value is exceeded, the user must re-authenticate. In addition, if the max_age value is set to 0 (max_age=0), this setting always requires the user to re-authenticate.
nonce A string that is used to associate a client session with a token to mitigate replay attacks. The value is passed through unmodified from the authentication request to the token. This is an optional property for authorization requests that return a code.
prompt A string that specifies whether the user is prompted to login for re-authentication. The prompt parameter can be used as a way to check for existing authentication, verifying that the user is still present for the current session. For prompt=none, the user is never prompted to login to re-authenticate, which can result in an error if authentication is required. For prompt=login, if time since last login is greater than the max-age, then the current session is stashed away in the flow state and treated in the flow as if there was no previous existing session. When the flow completes, if the flow’s user is the same as the user from the stashed away session, the stashed away session is updated with the new flow data and persisted (preserving the existing session ID). If the flow’s user is not the same as the user from the stashed away session, the stashed away session is deleted (logout) and the new session is persisted.
redirect_uri A string that specifies the URL that specifies the return entry point of the application. This is a required property.
request A 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.
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.
response_type A string that specifies the code or token type returned by an authorization request. Options are token, id_token, and code. This is a required property.
scope A string that specifies permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.
state A string that specifies an optional parameter that is used to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter.