PingOne Platform APIs

External OAuth Servers

The PingOne /v1/environments/{{envID}}/externalOAuthServers endpoint provides operations to create, read, update, and delete external OAuth server resources in PingOne.

Refer to Using an external authorization server in PingOne Authorize AAM in the PingOne Admin Guide for more information.

PingOne enforces a limit of 25 External OAuth Servers per environment.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

External OAuth server data model

Property Type Required Mutable Description

description

String

Optional

Mutable

A description of the External OAuth Server. Maximum length 1024.

id

UUID

Required

Immutable

The ID of the External OAuth Server.

issuers

Array of Strings

Optional

Mutable

Lists the expected issuer value(s) used by the External OAuth Server. The runtime will expect the value of a bearer token’s iss claim to match one of these expected issuer values. Array size must be between 1-8. Array elements must be between 1-1024.

name

String

Required

Mutable

The name of the External OAuth Server. Must be unique to the environment. Length must be between 1-256.

type

String

Required

Mutable

The type of External OAuth Server. The only accepted value is EXTERNAL, which indicates that the External OAuth Server is not PingOne SSO.

validation

Object

Required

Mutable

A container object for fields related to runtime validation of access tokens issued by the External OAuth Server.

validation.clockSkewTolerance

Number

Optional

Mutable

Specifies an allowable clock skew tolerance in seconds. When validating certain time-based token claims (nbf, exp), the runtime will tolerate time differences as specified by the value. The value must be zero or a positive integer. The default value is 0.

validation.jwks

String

Optional (see description)

Mutable

A JWKS document containing the External OAuth Server’s public signing keys. Required if type is JWKS. Must be a valid JWKS per RFC 7517 and not exceed 16kB.

validation.jwksUrl

String

Optional (see description)

Mutable

The URL of the External OAuth Server’s JWKS endpoint. Required if type is JWKS_URL. Length must be between 1-1024. Must use the HTTPS protocol scheme and satisfy an SSRF risk check.

validation.type

String

Required

Mutable

Indicates the validation strategy that will be used by the AAM runtime. Accepts only one of the following values: JWKS_URL, which indicates that the AAM runtime will retrieve JWK signing keys from a JWKS endpoint or JWKS, which indicates that the AAM runtime will use a set of JWK signing keys from a JWKS stored in the configuration.

Limiting and filtering data

You can limit the number of results returned on the Read All External OAuth Servers request with the limit parameter. Refer to Paging and ordering collections for more information about use of the limit parameter, as well as other methods of controlling pagination.

You can filter response data by applying a SCIM filtering expression to the Read All External OAuth Servers request. These SCIM operators can be applied to the following attributes:

  • co (contains)

    Supported attributes: name

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

External OAuth servers errors

In addition to the general error codes, external OAuth server operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or REQUIRED_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST /externalOAuthServers or PUT /externalOAuthServers/{externalOAuthServerId} request omits the required name, type, validation, or validation.type property, or provides a blank validation.jwks, validation.jwksUrl, or issuers element value when required by the validation type

Details: must not be null for an omitted name or type, must not be blank for a blank validation.jwks, validation.jwksUrl, or issuers element, for example Validation Error : [name must not be null]

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>] or, for a duplicate issuer, External OAuth server issuers must not contain duplicate values.

When and details

When: A POST or PUT /externalOAuthServers request provides a type that is not EXTERNAL or a validation.type that is not JWKS or JWKS_URL, a validation.jwks value together with a validation.type of JWKS_URL (or a validation.jwksUrl value with a type of JWKS), a validation.jwks value that is not a well-formed JWKS document or contains no keys, a validation.jwksUrl value that is not a valid URL, does not use the HTTPS protocol scheme, or fails the SSRF risk check, or an issuers array with duplicate values

Details: Describes the failing property, such as must only contain jwks when type is JWKS with target validation, must only contain jwksUrl when type is JWKS_URL with target validation, must be a well formatted JWKS object (see RFC 7517) and must contain keys with target validation.jwks, is not a valid URL, must be https, and must resolve to a valid address with target validation.jwksUrl, or The issuer '<issuer>' appears more than once. with target issuers[<index>].

400

INVALID_DATA

OUT_OF_RANGE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT /externalOAuthServers request provides an issuers array with fewer than 1 or more than 8 entries, an issuers element longer than 1024 characters, a validation.jwksUrl value longer than 1024 characters, a validation.jwks value larger than 16 kB, a validation.clockSkewTolerance value that is negative, or a description longer than 1024 characters

Details: Describes the failing property and its bound, such as size must be between 1 and 8 for an out-of-range issuers array, size must be between 1 and 1024 for an out-of-range issuers element, must be greater than or equal to 0 for a negative validation.clockSkewTolerance, or must be smaller than 16 KB for an oversized validation.jwks

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT /externalOAuthServers request specifies a name that already exists in the environment

Details: The target is name; the message is A resource with the specified name already exists.

400

REQUEST_FAILED

ITEM_LIMIT_EXCEEDED

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST /externalOAuthServers request would exceed the limit of 25 external OAuth servers per environment

Details: The limit on amount of items that can be created is exceeded. with no target

400

REQUEST_FAILED

INVALID_PARAMETER

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A GET /externalOAuthServers request provides a cursor value that cannot be parsed as a UUID

Details: The target is cursor; the message is Invalid cursor parameter value.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A DELETE /externalOAuthServers/{externalOAuthServerId} request targets an external OAuth server that is still referenced by at least one API service

Details: This external OAuth server is still in use by at least one API service.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the authz:read:externalOAuthServer permission (GET operations), the authz:create:externalOAuthServer permission (POST), the authz:update:externalOAuthServer permission (PUT), or the authz:delete:externalOAuthServer permission (DELETE)

Details: None

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: The externalOAuthServerId does not identify an external OAuth server in the environment

Details: None