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.
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:
|
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. |
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.
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 |
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. |