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 /{{envID}}/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 Type Required? Mutable? Description
acr_values String Optional Mutable Either a single DaVinci policy (identified by the flow policy ID), or one or more PingOne sign-on policies by name (space-separated). The PingOne sign-on policies can be the predefined sign-on policies, Single_Factor and Multi_Factor, or any custom defined sign-on policy names. The PingOne sign-on policy names should be listed in order of preference, and they must be assigned to the application.
client_assertion String Optional Mutable A JWT that contains a signed assertion with the application’s credentials. This property is required if the application’s tokenEndpointAuthMethod is set to either PRIVATE_KEY_JWT or CLIENT_SECRET_JWT.
client_assertion_type String Optional Mutable A string that specifies the client assertion type. The value of this property must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer. This property is required if the application’s tokenEndpointAuthMethod is set to either PRIVATE_KEY_JWT or CLIENT_SECRET_JWT.
client_id String Required Immutable The application’s UUID.
client_secret String Required Immutable The application’s client secret.
code String Optional Immutable the authorization code returned by the authorization server. This property is required only if the grant_type is set to authorization_code.
code_challenge String Optional Immutable 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 String Optional Mutable 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_verfier String Optional Immutable 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 String Optional Mutable The grant type of the token request. Options are authorization_code, implicit, refresh_token, and client_credentials.
login_hint String Optional Mutable 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 Token Optional Immutable 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.
mobilePayload Parameter Optional Mutable Used by mobile applications leveraging PingOne MFA SDK. See Implement automatic pairing of native app as MFA authenticator app.
max_age String Optional Mutable 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. If the max_age value is set to 0 (max_age=0), the user is always required to re-authenticate.
nonce String Optional Immutable 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 String Optional Mutable 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 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 session, the stashed session is deleted (logout) and the new session is persisted.
redirect_uri String Required Mutable The URL of the return entry point of the application.
refreshTokenRollingGracePeriodDuration Integer Optional Mutable The number of seconds that a refresh token may be reused after having been exchanged for a new set of tokens. This is useful in the case of network errors on the client. Valid values are between 0 and 86400 seconds. Null is treated the same as 0.
request Token Optional Immutable 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 the HS256 signing algorithm). 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.
For more information, see Create a request property JWT.
response_mode String Optional Mutable The 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 in the PingOne Developer Guide.
response_type String Required Mutable The code or token type returned by an authorization request. Options are token, id_token, and code.
scope String Optional Mutable Permissions that determine the resources that the application can access. This parameter is not required, but it is needed to specify accessible resources.
state String Optional Mutable Used to maintain state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter.
subject_token String Required Immutable The security token that represents the identity of the PingFederate cluster (or other client type) that requires access to PingOne services.
subject_token_type String Required Immutable The type of the security token provided in the subject_token property. Options are pingone_gateway_credential.
token String Required Immutable 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 Application Operations. 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.

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Service Event
applications SECRET.UPDATED
applications SECRET.READ
applications GRANT.CREATED
applications GRANT.UPDATED
applications GRANT.DELETED
resources RESOURCE.CREATED
resources RESOURCE.UPDATED
resources RESOURCE.DELETED
resources SCOPE.CREATED
resources SCOPE.UPDATED
resources SCOPE.DELETED
resources ATTRIBUTE.CREATED
resources ATTRIBUTE.UPDATED
resources ATTRIBUTE.DELETED
resources SECRET.UPDATED
resources SECRET.READ

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.