PingOne integrates with applications that use standards-compliant protocols by taking on the role of an OpenID Connect provider and OAuth 2 authorization server. In this capacity, PingOne provides the framework for connected applications to access protected HTTP resources. For more information about OpenID Connect and OAuth 2, see the OpenID Connect 1.0 spec and the OAuth 2.0 Authorization Framework RFC6749.

The PingOne authorization endpoint /{environmentId}/as/authorize is used to interact with the resource owner and obtain an authorization grant. For more information and additional examples, see Authorization and authentication by application type.

OpenID Connect/OAuth2 data model

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.
code_verifier A large random string used in a PKCE authorize request. This string is used to create the code_challenge value passed to the authorization server in the request. The length an character set requirements for the code_verifier string is documented in Section 4.1 of RFC7636.
grant_type A string that specifies the grant type of the token request. Options are authorization_code, implicit, refresh_token, and client_credentials.
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.
login_hint_token A token 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.
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. 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.
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.
token A string that specifies the token string. This is a required property for token introspection and token revocation.

Application access control conditions

You can configure OpenID Connect applications for access control by setting the accessControl property on the application. For more information about accessControl properties, see Applications. When accessControl properties are set for an application, the user must meet the requirements specified by these application properties to get a token. If the user attempts to authenticate and the grant_type is either authorization_code or implicit, then the application’s accessControl conditions are evaluated to determine whether the user can be issued a token.

The token (or tokens) is minted if the user meets the application’s access control conditions. If the conditions are not met, the token (or tokens) is not issued and an ACCESS_FAILED error is returned. If access is denied, a USER.ACCESS_DENIED event is published; otherwise, a USER.ACCESS_ALLOWED event is published.

For more information, see Control access to applications through roles and groups.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You weren’t authenticated to perform this operation.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.