--- title: OpenID Connect/OAuth 2 description: 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, refer to the OpenID Connect 1.0 spec and the OAuth 2.0 Authorization Framework RFC6749. component: pingone-api page_id: pingone-api:auth:openid-connect-oauth-2 canonical_url: https://developer.pingidentity.com/pingone-api/auth/openid-connect-oauth-2.html section_ids: openid-connectoauth2-data-model: OpenID Connect/OAuth2 data model application-access-control-conditions: Application access control conditions openid-connectoauth2-events-generated: OpenID Connect/OAuth2 events generated response-codes: Response codes --- # OpenID Connect/OAuth 2 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, refer to the [OpenID Connect 1.0](https://openid.net/specs/openid-connect-core-1_0.html) spec and the [OAuth 2.0 Authorization Framework RFC6749](https://tools.ietf.org/html/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, refer to [Authorization and authentication by application type](../foundations/authentication-concepts/authorization-and-authentication-by-application-type.html). ## 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. | | `actor_token` | String | Optional | Mutable | An optional token representing the actor in a token exchange grant request. Learn more in [Token exchange grant type](../foundations/authentication-concepts/authorization-flow-by-grant-type/token-exchange-grant-type.html). | | `actor_token_type` | String | Optional | Mutable | The type of token provided by the `actor_token` property. Options are `urn:ietf:params:oauth:token-type:access_token` or `urn:ietf:params:oauth:token-type:id_token`. | | `auth_req_id` | String | Required | Immutable | This property is required when `grant_type` is `ciba`. This property is returned from the CIBA authorization endpoint and passed to the token endpoint. | | `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. \*Note: This parameter is optional for `GET /{{envID}}/as/idp-signoff?id_token_hint={{idToken}}`. | | `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](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1). The computation for the `code_challenge` string is documented in [Section 4.2 of RFC7636](https://tools.ietf.org/html/rfc7636#section-4.2). | | `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](https://tools.ietf.org/html/rfc7636#section-4.1). | | `grant_type` | String | Optional | Mutable | The grant type of the token request. Options are `authorization_code`, `implicit`, `refresh_token`, `client_credentials`, `token_exchange`, and `ciba`. | | `id_token_hint` | String | Optional\* | Mutable | The previously issued ID token used to indicate the identity of the user. This is passed to the logout endpoint as a hint about the user's current authenticated session with the client. \*Note: This parameter is required for `GET /{{envID}}/as/idp-signoff?id_token_hint={{idToken}}`. | | `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. Refer to [Implement automatic pairing of native app as MFA authenticator app](../native-sdks/pingone-mfa-mobile-sdks/pingone-mfa-mobile-sdk-flows.html). | | `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. | | `post_logout_redirect_uri` | String | Optional | Mutable | The URL to which the browser is redirected after a logout has been performed. When `id_token_hint` is specified, this URI must match one of the `postLogoutRedirectUri` values for the application using `id_token_hint`. If `post_logout_redirect_uri` is specified, and it does not match one of the `postLogoutRedirectUri` values of any enabled application in the specified environment, this condition is handled as an un-redirectable error. | | `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. | | `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, refer to [Create a request property JWT](auth-config-options/create-a-request-property-jwt.html). | | `requested_token_type` | String | Optional | Mutable | Specifies the type of token returned by PingOne when using token exchange. Options are `urn:ietf:params:oauth:token-type:access_token`. | | `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, refer to the [ResponseModes](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes) section of the *OAuth 2.0 Multiple Response Type Encoding Practices* specification. For non-redirect use case information, refer to [Redirect and non-redirect authentication flows](auth-config-options/browserless-authentication-flow-options.html). | | `response_type` | String | Required | Mutable | The code or token type returned by an authorization request. Options are `token`, `id_token`, and `code`. It's possible to reference multiple response types. Refer to the OpenID spec [OAuth 2.0 Multiple Response Type Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html) for details. | | `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. Refer to [Authorization](openid-connect-oauth-2/authorize-intro.html) for details when using the `offline_access` value here. | | `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. Required when `grant_types` is set to `token-exchange`. | | `subject_token_type` | String | Required | Immutable | The type of the security token provided in the `subject_token` property. Options are `pingone_gateway_credential` when used with the PingOne Gateway service, or `urn:ietf:params:oauth:token-type:access_token` or `urn:ietf:params:oauth:token-type:id_token` when used for token exchange. Required when `grant_types` is set to `token-exchange`. | | `token` | String | Required | Immutable | The token string. This is a required property for token introspection and token revocation. | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | PingOne licenses can disable access to specific scopes (and their associated permissions) based on the capabilities allowed by the license package. For more information about restricted scopes, refer to [Access services through scopes and roles](../foundations/pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles.html). | ### 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, refer to [Application Operations](../platform/applications/applications-1.html). 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. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------- | | | If the user already has an access token, application access restrictions are not applied to refresh token or to token introspection operations. | For more information, refer to [Control access to applications through roles and groups](../foundations/pingone-roles-scopes-and-permissions/control-access-to-applications-through-roles-and-groups.html). ## OpenID Connect/OAuth2 events generated Refer to [Audit Reporting Events](../platform/reference/audit-reporting-events.html) for the events generated. ### 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. | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Applications in an environment configured to use a custom domain should use the custom domain URL in the `{{authPath}}` instead of the default PingOne domain. For more information about custom domains, refer to [Custom Domains](../platform/custom-domains.html). In addition, URLs are generated based on the inbound initial authorize call. For example, if the environment's custom domain is `acme.com`, but the initial call is from `https://auth.pingone.com/{{envID}}/as/authorize`, then the generated URLs will have a format of `https://auth.pingone.com/{{envID}}/…​`. If the initial call is from `https://acme.com/as/authorize`, the generated URLs will have a format of `https://acme.com/…​`. | > **Collapse: Related topics** > > * [Access tokens and ID tokens](../foundations/authentication-concepts/access-tokens-and-id-tokens.html) > > * [Token claims](../foundations/authentication-concepts/access-tokens-and-id-tokens/token-claims.html) > > * [Authorization flow by grant type](../foundations/authentication-concepts/authorization-flow-by-grant-type.html) > > * [Authorization and authentication by application type](../foundations/authentication-concepts/authorization-and-authentication-by-application-type.html) > > * [Access services through scopes and roles](../foundations/pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles.html)