PingOne Platform APIs

Application Operations

The Applications service implements operations to create, read, update, and delete, applications resources.

You need the Client Application Developer role to perform operations on application resources.

Refer also to Authorization and authentication by application type

Cross-origin resource sharing

PingOne supports cross-origin resource sharing (CORS), which gives applications running at different domains permission to access resources on PingOne servers. For example, an application at https://myapp.com that uses PingOne to authenticate users needs to request permission to access resources at https://auth.pingone.com before authentication operations are executed. In this case, a request is made to the resource owner (auth.pingone.com) from the requestor (myapp.com) using CORS headers to ask for access privileges. The response from auth.pingone.com returns the CORS Access-Control-Allow-Origin header with a value that confirms the requestor’s access rights.

PingOne servers are configured to trust all origins when using access tokens. However, when requesting sensitive resources that use PingOne session cookies for authentication, only specified origins will be trusted. The following endpoints require session cookies for authentication, and only the origins specified in the application’s corsSettings property will be trusted when calling these endpoints:

/{envId}/as/authorize
/{envId}/as/resume
/{envId}/as/signoff
/{envId}/rp/authenticate
/{envId}/rp/callback/{callbackId}
/{envId}/saml20/idp/sso
/{envId}/saml20/idp/startsso
/{envId}/saml20/resume
/{envId}/saml20/idp/slo
/{envId}/wsf/sts/{appId}
/{envId}/wsf/mex/{appId}
/{envId}/wsf/prp/{appId}
/{envId}/wsf/prp/resume

When using session cookies for authentication, no origins will be trusted when calling these endpoints:

/{envId}/as/txs
/{envId}/saml20/sp/sso
/{envId}/saml20/sp/acs
/{envId}/saml20/sp/jwtacs

Consequently, when defining an application’s connection to PingOne, you generally do not need to add your application’s domain to a list of trusted origins. Cross-origin requests that use HTTP methods to modify the resource, such as PUT, PATCH, POST, and DELETE, trigger a preflight request to ensure that the initial request can be sent. The browser initiates a preflight HTTP OPTIONS request to verify that the HTTP method used in the actual request is allowed. In these cases, the response from auth.pingone.com to the preflight request returns a response with the CORS Access-Control-Allow-Methods header to specify the allowed methods.

When making CORS requests, only these headers can be used:

  • Accept

  • Accept-Language

  • Content-Language

  • Content-Type

  • Range

  • Authorization

  • Content-Length

  • Cookie

  • Correlation-Id

  • Origin

  • Origin-Cookies

  • Referer or Referrer

  • X-Amz-Date

  • X-Amz-Security-Token

  • X-Api-Key

  • X-client-version

  • X-Content-Type-Options

When accessing CORS responses, you’re restricted to reading only the Correlation-Id header (as well as the request body).

Attempting to submit or access headers that are not listed above may prevent you from making CORS requests or reading the responses.

Applications data models

The following applications properties tables show the base data model for properties that apply to all application protocols, and the specific properties for the OpenID Connect (OIDC), SAML, and WS-Federation application protocols.

Applications base data model

Property Type Required? Mutable? Description

accessControl.role.type

String

Optional

Mutable

The user role required to access the application. Options are ADMIN_USERS_ONLY. A user is an admin user if the user has one or more of the following roles: Organization Admin, Environment Admin, Identity Data Admin, or Client Application Developer.

accessControl.group.type

String

Optional

Mutable

The group type required to access the application. Options are ANY_GROUP (the actor must belong to at least one group listed in the accessControl.group.groups property) and ALL_GROUPS (the actor must belong to all groups listed in the accessControl.group.groups property).

accessControl.group.groups

String[]

Optional

Mutable

The group IDs for the groups the actor must belong to for access to the application.

createdAt

Date

N/A

Read-only

The time the resource was created.

description

String

Optional

Mutable

The description of the application.

enabled

Boolean

Required

Mutable

The current enabled state of the application. Options are true (enabled) or false (disabled).

environment.id

String

Required

Read-only

The PingOne environment associated with the application.

externalId

String

Optional

Mutable

For applications whose type is PORTAL_LINK_APP, you can use externalId to specify an external ID that should be used for the application in contexts such as targeted risk policies. Note that PORTAL_LINK_APP applications that do not have an external ID specified are not displayed in the list of applications when defining a targeted risk policy in the UI.

hiddenFromAppPortal

Boolean

Optional

Mutable

Whether the application is hidden in the application portal despite the configured group access policy.

homePageUrl

String

Optional

Mutable

The custom home page URL for the application.

icon

Object

Optional

Mutable

The HREF and the ID for the application icon.

id

String

Required

Read-only

The application UUID.

loginPageUrl

String

Optional

Mutable

The custom login page URL for the application. If you set the loginPageUrl property for applications in an environment that sets a custom domain, the URL should include the top-level domain and at least one additional domain level. Warning: To avoid issues with third-party cookies in some browsers, a custom domain must be used, giving your PingOne environment the same parent domain as your authentication application. For more information about custom domains, refer to Custom domains. If a loginPageUrl value is not specified, the OIDC app resource includes a Ping-provided login page at https://{{apps domain}}/{{envId}}/signon/ or https://{{custom domain}}/signon/. If a PingOne authentication session exists and the sign-on policy does not indicate that re-authentication is needed, a login page is not displayed (either Ping-provided or custom).

name

String

Required

Mutable

The name of the application.

protocol

String

Required

Immutable

The protocol used by the application. Options are OPENID_CONNECT, SAML, WS_FED, and EXTERNAL_LINK.

type

String

Required

Mutable

The application type. Options are WEB_APP, NATIVE_APP, SINGLE_PAGE_APP, SERVICE, CUSTOM_APP, WORKER, PING_ONE_SELF_SERVICE, PING_ONE_ADMIN_CONSOLE, PING_ONE_PORTAL, TEMPLATE_APP, and PORTAL_LINK_APP.

updatedAt

Date

N/A

Read-only

The time the resource was last updated.

Applications OIDC settings data model

Property Type Required? Mutable? Description

additionalRefreshTokenReplayProtectionEnabled

Boolean

Optional

Mutable

PingOne detects a replay attack when a refresh token is reused outside of its specified grace period (refer to below for information on refreshTokenRollingGracePeriodDuration). If the refresh token is revoked because of a replay attack, then PingOne also revokes any associated access tokens if, and only if, this setting is enabled. Setting this property to null equates to a false setting. For more information about refresh token rotation, refer to Refresh token rotation in the PingOne admin guide.

allowWildcardInRedirectUris

Boolean

Optional

Mutable

Whether wildcards are allowed in redirect URIs. For more information, refer to Wildcards in Redirect URIs.

assignActorRoles

Boolean

Optional

Mutable

Indicates whether the permissions service should assign to the application the roles of the actor creating the application (defaults to true). This property is set only on the POST request. The property is ignored when included in a PUT request. Best Practice: When creating a Worker app, the best practice is to set this value to false. This is for security purposes, to ensure you assign only the minimal set of permissions necessary for the Worker app.

corsSettings

Object

Optional

Mutable

Enables you to customize how the Authorization and Authentication APIs interact with CORS requests that reference the application. If omitted, the application allows CORS requests from any origin except for operations that expose sensitive information (such as, operations from /as/authorize and /as/token). We recommend you use corsSettings, rather than omitting this property.

corsSettings.behavior

String

Required

Mutable

Options are "ALLOW_NO_ORIGINS" and "ALLOW_SPECIFIC_ORIGINS". ALLOWS_NO_ORIGINS rejects all CORS requests. ALLOW_SPECIFIC_ORIGINS rejects all CORS requests except those listed in corsSettings.origins.

corsSettings.origins

String[]

Optional

Mutable

This must be specified when corsSettings.behavior is ALLOW_SPECIFIC_ORIGINS, and must be omitted or empty when corsSettings.behaviour is ALLOW_NO_ORIGINS. Limited to 20 values. The values are the origins from which CORS requests to the Authorization and Authentication APIs are allowed. Each value is an HTTP or HTTPS URL without a path. The host may be a domain name (including localhost), or an IPv4 address. Subdomains can be specified using the wildcard (*) to match any string.

devicePathId

String

Optional

Mutable

A string that specifies a unique identifier within an environment for a device authorization grant flow to provide a short identifier to the application. This property is ignored when the deviceCustomVerificationUri property is configured. The string can contain any letters, numbers, and some special characters (regex: a-zA-Z0-9_-). It can have a length of no more than 50 characters (min/max=1/50).

deviceCustomVerificationUri

String

Optional

Mutable

A string that specifies an optional custom verification URI that is returned for the /device_authorization endpoint.

deviceTimeout

Integer

Required

Mutable

An integer that specifies the length of time (in seconds) that the userCode and deviceCode returned by the /device_authorization endpoint are valid. This property is required only for applications in which the grantTypes property is set to device_code. The default value is 600 seconds. It can have a value of no more than 3600 seconds (min/max=1/3600).

devicePollingInterval

Integer

Required

Mutable

An integer that specifies the frequency (in seconds) for the client to poll the /as/token endpoint. This property is required only for applications in which the grantTypes property is set to device_code. The default value is 5 seconds. It can have a value of no more than 60 seconds (min/max=1/60).

grantTypes

String[]

Optional

Mutable

The grant type for the authorization request. Options are authorization_code, implicit, refresh_token, device_code, and client_credentials.

idpSignoff

Boolean

Optional

Mutable

Set this to true to allow an application to request to terminate a user session using only the ID token. The application is not required to have access to the session token cookie. Refer to GET IdP Signoff for more information.

includeX5t

Boolean

Optional

Mutable

Specifies whether tokens signed for this application include the x5t signature header in the signed JWT. Refer to JSON Web Signature (JWS), section "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter.

initiateLoginUri

String

Optional

Mutable

The URI to use for third-parties to begin the sign-on process for the application. If specified, PingOne redirects users to this URI to initiate SSO to PingOne. The application is responsible for implementing the relevant OIDC flow when the initiate login URI is requested. This property is required if you want the application to appear in the PingOne Application Portal. Refer to the OIDC specification section Initiating Login from a Third Party for more information.

jwks

String

Optional

Mutable

A JWKS string that validates the signature of signed JWTs for applications that use the PRIVATE_KEY_JWT option for the tokenEndpointAuthMethod. This property is required when tokenEndpointAuthMethod is PRIVATE_KEY_JWT and the jwksUrl property is empty. For more information, refer to Create a private_key_jwt JWKS string. This property is also required if the optional request property JWT on the authorize endpoint is signed using the RS256 (or RS384, RS512) signing algorithm and the jwksUrl property is empty. For more infornmation about signing the request property JWT, refer to Create a request property JWT.

jwksUrl

String

Optional

Mutable

A URL (supports https:// only) that provides access to a JWKS string that validates the signature of signed JWTs for applications that use the PRIVATE_KEY_JWT option for the tokenEndpointAuthMethod. This property is required when tokenEndpointAuthMethod is PRIVATE_KEY_JWT and the jwks property is empty. For more information, refer to Create a private_key_jwt JWKS string. This property is also required if the optional request property JWT on the authorize endpoint is signed using the RS256 (or RS384, RS512) signing algorithm and the jwks property is empty. For more infornmation about signing the request property JWT, refer to Create a request property JWT.

kerberos.key

Object

Optional

Mutable

A Relationship object containing the certificate issuer (root CA).

kerberos.key.id

String

Optional

Immutable

The unique identifier for the Kerberos key. Required if kerberos.key is specified.

mobile.bundleId

String

Optional

Immutable

The bundle associated with the application, for push notifications in native apps. The value of the bundleId property is unique per environment, and once defined, is immutable. Used only for applications for the Apple ecosystem.

mobile.huaweiAppId

String

Optional

Immutable

The unique identifier for the app on the device and in the Huawei Mobile Service AppGallery. The value of the mobile.huaweiAppId property is unique per environment, and once defined, is immutable. Used only for applications for the Huawei ecosystem.

mobile.huaweiPackageName

String

Optional

Immutable

The package name associated with the application, for push notifications in native apps. The value of the mobile.huaweiPackageName property is unique per environment, and once defined, is immutable. Used only for applications for the Huawei ecosystem.

mobile.integrityDetection.googlePlay

Object

Optional

Mutable

Object that contains the credentials required for using Google’s Play Integrity API for integrity detection.

mobile.integrityDetection.googlePlay.verificationType

String

Optional

Mutable

The type of verification that should be used. The possible values are GOOGLE and INTERNAL. Using internal verification will not count against your Google API call quota. The value you select for verificationType determines what other parameters you must provide. When set to GOOGLE, you must provide serviceAccountCredentials. When set to INTERNAL, you must provide decryptionKey and verificationKey.

mobile.integrityDetection.googlePlay.serviceAccountCredentials

String

Optional

Mutable

Contents of the JSON file that represents your Service Account Credentials. This parameter must be provided if you have set mobile.integrityDetection.googlePlay.verificationType to GOOGLE.

mobile.integrityDetection.googlePlay.decryptionKey

String

Optional

Mutable

Play Integrity verdict decryption key from your Google Play Services account. This parameter must be provided if you have set mobile.integrityDetection.googlePlay.verificationType to INTERNAL.

mobile.integrityDetection.googlePlay.verificationKey

String

Optional

Mutable

Play Integrity verdict signature verification key from your Google Play Services account. This parameter must be provided if you have set mobile.integrityDetection.googlePlay.verificationType to INTERNAL.

mobile.integrityDetection.mode

String

Optional

Mutable

Indicates whether device integrity detection takes place on mobile devices, for the application’s enrollment and authentication events. The possible values are ENABLED or DISABLED.

mobile.integrityDetection.excludedPlatforms

Array

Optional

Mutable

You can enable device integrity checking separately for Android and iOS by setting mobile.integrityDetection.mode to ENABLED and then using this property to specify an OS where you do not want to use device integrity checking. The possible values are GOOGLE and IOS. Note that this is implemented as an array even though currently you can only include a single value.

mobile.integrityDetection.cacheDuration.amount

Integer

Optional

Mutable

The duration between successful integrity detection calls. Every attestation request entails a certain time tradeoff. You can choose to cache successful integrity detection calls for a predefined duration, between a minimum of 1 minute and a maximum of 48 hours. If mobile.integrityDetection.mode is ENABLED, the cache duration must be set.

mobile.integrityDetection.cacheDuration.units

String

Optional

Mutable

The time units used for mobile.integrityDetection.cacheDuration.amount. The possible values are MINUTES or HOURS.

mobile.packageName

String

Optional

Immutable

The package name associated with the application, for push notifications in native apps. The value of the mobile.packageName property is unique per environment, and once defined, is immutable. Used only for applications for the Google ecosystem.

mobile.passcodeGracePeriod

Integer

Optional

Mutable

To cover time synchronization issues, you can use passcodeGracePeriod to customize the grace period during which the passcode can still be used even after the passcode has been refreshed. The value of the parameter should be the number of windows to use (min 1, max 10). In this context, a window is equal to the passcode refresh period in either direction. For example, if you defined a passcode refresh duration of 30 seconds and a grace period of 2 windows, the passcode is valid for 150 seconds (from 60 seconds behind the time of issue until 60 seconds past the expiration time). When passcodeGracePeriod is not included, the default value used is 5 windows.

mobile.passcodeRefreshDuration.duration

Integer

Optional

Mutable

The amount of time a passcode should be displayed before being replaced with a new passcode. Must be between 30 and 60 (seconds).

mobile.passcodeRefreshDuration.timeUnit

String

Optional

Mutable

The type of time unit for mobile.passcodeRefreshDuration.duration. Currently, this must be SECONDS.

mobile.push.numberMatching.type

String

Optional

Mutable

This option is used to specify the type of number matching that should be used in MFA policies where number matching has been enabled for the application (refer to the numberMatching.enabled parameter in Device Authentication Policies). The possible values are: <li>SELECT_NUMBER - Users must select the correct number from a group of three numbers</li> <li>ENTER_MANUALLY - Users must enter the number that was shown</li>

mobile.uriPrefix

String

Optional

Mutable

A URI prefix that enables direct triggering of the mobile application when scanning a QR code. The URI prefix can be set to a universal link with a valid value (which can be a URL address that starts with HTTP:// or HTTPS://, such as https://www.acme.com), or an app schema, which is just a string and requires no special validation.

opSessionCheckEnabled

Boolean

Optional

Mutable

When enabled, PingOne includes the session_state parameter in the authentication response, per spec with OpenID Connect Session Management 1.0. Refer to OIDC Session Management in the Developer’s Foundations for more information. This property is disabled by default.

parRequirement

Enum

Optional

Mutable

Whether pushed authorization requests (PAR) are required. Options are REQUIRED and OPTIONAL. The default value is OPTIONAL.

parTimeout

Integer

Optional

Mutable

PAR timeout in seconds. Must be between 1 and 600. The default value is 60.

pkceEnforcement

String

Optional

Mutable

Specifies how PKCE request parameters are handled on the authorize request. Options are: OPTIONAL: PKCE code_challenge is optional and any code challenge method is acceptable. REQUIRED: PKCE code_challenge is required and any code challenge method is acceptable. S256_REQUIRED: PKCE code_challenge is required and the code_challenge_method must be S256.

postLogoutRedirectUris

String[]

Optional

Mutable

The URLs that the browser can be redirected to after logout.

redirectUris

String[]

Optional

Mutable

The callback URI for the authentication response.

refreshTokenDuration

Integer

Optional

Mutable

The lifetime in seconds of the refresh token. If a value is not provided, the default value is 2592000, or 30 days. Valid values are between 60 and 2147483647. If the refreshTokenRollingDuration property is specified for the application, then this property must be less than or equal to the value of refreshTokenRollingDuration. After this property is set, the value cannot be nullified. This value is used to generate the value for the exp claim when minting a new refresh token.

refreshTokenRollingDuration

Integer

Optional

Mutable

The number of seconds a refresh token can be exchanged before re-authentication is required. If a value is not provided, the refresh token is valid forever. Valid values are between 60 and 2147483647. After this property is set, the value cannot be nullified. This value is used to generate the value for the exp claim when minting a new refresh token.

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.

requestScopesForMultipleResourcesEnabled

Boolean

Optional

Mutable

Specifies whether the application can request scopes from multiple custom resources. The default value is false. For more information about scopes and access tokens, refer to Resource Scopes.

requireSignedRequestObject

Boolean

Optional

Mutable

Indicates that the Java Web Token (JWT) for the request query parameter is required to be signed. If false or null (default), a signed request object is not required. Both supportUnsignedRequestObject and this property cannot be set to true.

responseTypes

String[]

Optional

Mutable

The code or token type returned by an authorization request. Options are TOKEN, ID_TOKEN, and CODE. For hybrid flows that specify CODE with TOKEN or ID_TOKEN, refer to Hybrid grant type.

signing

Object

Optional

Mutable

Configuration for the signing key. If absent, application tokens will be signed and verified by the PingOne default key at runtime. This property only applies to OIDC applications of type WEB_APP, NATIVE_APP, SINGLE_PAGE_APP, and CUSTOM_APP.

signing.keyRotationPolicy

Object

Required

Mutable

Contains the Key Rotation Policy (KRP) ID. This property is required if signing is set.

signing.keyRotationPolicy.id

String

Required

Mutable

Reference to a KRP ID from certificate management. This property is required if signing is set.

supportUnsignedRequestObject

Boolean

Optional

Mutable

Indicates whether the Java Web Token (JWT) for the request query parameter is allowed to be unsigned. If false or null (default), an unsigned request object is not allowed. Both requireSignedRequestObject and this property cannot be set to true.

tags

String[]

Optional

Mutable

An array that specifies the list of labels associated with the application. Options are PING_FED_CONNECTION_INTEGRATION. Only applicable for Create Application (OIDC Protocol - PingFederate Worker App).

targetLinkUri

String

Optional

Mutable

The URI for the application. If specified, PingOne will redirect application users to this URI after a user is authenticated. In the PingOne admin console, this becomes the value of the target_link_uri parameter used for the Initiate Single Sign-On URL field.

template

Object

Optional

Mutable

Valid only when the application type is TEMPLATE_APP. This identifies the application as integration in Integration Catalog. (by integration.id and version.id) and provides key-value map of parameters needed by the integration

template.configuration

Object

Required

Mutable

Contains a key/value map of the parameters required by the integration in Integration Catalog.

template.integration.id

String

Required

Mutable

The UUID of the integration in Integration Catalog.

template.version.id

String

Required

Mutable

The UUID of the integration version in Integration Catalog.

tokenEndpointAuthMethod

String

Optional

Mutable

The client authentication methods supported by the token endpoint. Options are NONE, CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, PRIVATE_KEY_JWT, and CLIENT_SECRET_JWT. If this property is not set, the default values for supported app types are: CLIENT_SECRET_BASIC for WEB_APP and WORKER types, NONE for NATIVE_APP, SINGLE_PAGE_APP, and CUSTOM_APP types (when CUSTOM_APP specifies a DEVICE_CODE grant type for device authorization). For PKCE authentication flows, the tokenEndpointAuthMethod must be set to NONE.

Applications OIDC settings data model for PING_ONE_SELF_SERVICE

For applications of type PING_ONE_SELF_SERVICE only. Ignored for all other application types.

Property Type Required? Mutable? Description

applyDefaultTheme

Boolean

Required

Mutable

If true, applies the default theme to the self service application.

enableDefaultThemeFooter

Boolean

Required

Mutable

If true, shows the default theme footer on the self service application. Applies only if applyDefaultTheme is also true.

logoutType

String

Optional

Mutable

The logout type for the self service application. This can be either OIDC_RP_INITIATED (the default) or SAML2_SLO.

manageDevicesViaMyAccountEnabled

Boolean

Optional

Mutable

When set to true, PingID users can manage their devices using the MyAccount app. This will also add the MyAccount app to all PingID policies that already include Device Management. To limit the scope of PingID users, ensure an MFA policy or MFA DaVinci flow policy limiting their scope is added to the MyAccount app. For more information, refer to Self service in the PingOne admin documentation.

Applications OIDC settings data model for PING_ONE_PORTAL

For applications of type PING_ONE_PORTAL only. Ignored for all other application types.

Property Type Required? Mutable? Description

applyDefaultTheme

Boolean

Required

Mutable

If true, applies the default theme to the app portal application.

logoutType

String

Optional

Mutable

The logout type for the app portal application. This can be either OIDC_RP_INITIATED (the default) or SAML2_SLO.

Applications SAML settings data model

Property Type Required? Mutable? Description

acsUrls

String[]

Required

Mutable

The Assertion Consumer Service URLs. The first URL in the list is used as default (there must be at least one URL).

assertionDuration

Integer

Required

Mutable

The assertion validity duration in seconds.

assertionSigned

Boolean

Optional

Mutable

Indicates whether the SAML assertion itself should be signed. The default value is true.

corsSettings

Object

Optional

Mutable

Enables you to customize how the Authorization and Authentication APIs interact with CORS requests that reference the application. If omitted, the application allows CORS requests from any origin except for operations that expose sensitive information (such as, operations from /as/authorize and /as/token). We recommend you use corsSettings, rather than omitting this property.

corsSettings.behavior

String

Required

Mutable

Options are "ALLOW_NO_ORIGINS" and "ALLOW_SPECIFIC_ORIGINS". ALLOWS_NO_ORIGINS rejects all CORS requests. ALLOW_SPECIFIC_ORIGINS rejects all CORS requests except those listed in corsSettings.origins.

corsSettings.origins

String[]

Optional

Mutable

This must be specified when corsSettings.behavior is ALLOW_SPECIFIC_ORIGINS, and must be omitted or empty when corsSettings.behavior is ALLOW_NO_ORIGINS. Limited to 20 values. The values are the origins from which CORS requests to the Authorization and Authentication APIs are allowed. Each value is an HTTP or HTTPS URL without a path. The host may be a domain name (including localhost), or an IPv4 address. Subdomains can be specified using the wildcard (*) to match any string.

defaultTargetUrl

String

Optional

Mutable

This is used as the RelayState parameter by the IdP to deep link into the application after authentication. This value can be overridden by the applicationUrl query parameter for GET Identity Provider Initiated SSO. Although both of these parameters are generally URLs, because they are used as deep links, this is not enforced. If neither defaultTargetUrl nor applicationUrl is specified during a SAML authentication flow, no RelayState value is supplied to the application. The defaultTargetUrl (or the applicationUrl) value is passed to the SAML application’s ACS URL as a separate RelayState key value (not within the SAMLResponse key value).

enableRequestedAuthnContext

Boolean

Optional

Mutable

Indicates whether requestedAuthnContext is taken into account in policy decision-making.

enableAlwaysAcceptAcsUrlInSignedAuthnRequest

Boolean

Optional

Mutable

If enabled (true), this indicates that when a service provider (SP) specifies an ACS URL in its AuthnRequest, and signs the AuthnRequest, then assuming the identity provider (IdP) can validate the signature, the IdP can accept the ACS URL as valid. This is so, regardless of whether the ACS URL is specified in acsUrls as an allowable ACS URL (refer to Applications SAML metadata settings data model). Enabling this setting is useful when an SP generates ACS URLs dynamically.

idpSigning.algorithm

String

Optional

Mutable

The algorithm used by the IdP signing key. Algorithms supported: SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withECDSA, SHA384withECDSA, and SHA512withECDSA.

idpSigning.key.id

String

Optional

Mutable

The certificate to be used by the identity provider to sign assertions and responses. If this property is omitted, the default signing certificate for the environment is used.

nameIdFormat

String

Optional

Mutable

The format of the Subject NameID attribute in the SAML assertion. Options are:

  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified: The Subject’s NameID format is not specified. Use this format if you are not sure which format to use.

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress: The Subject’s NameID format is in the form of an email address.

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent: The Subject’s NameID format is an opaque unique identifier for a user that retains the same value over time.

  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient: The Subject’s NameID format is a randomly generated identifier. A different value is used for each SSO for a given user.

responseSigned

Boolean

Optional

Mutable

Indicates whether the SAML assertion response itself should be signed. The default value is False.

sessionNotOnOrAfterDuration

Integer

Optional

Mutable

Update this value if the SAML application requires a different SessionNotOnOrAfter attribute value within the AuthnStatement element than the NotOnOrAfter value set by the assertionDuration property.

sloBinding

String

Optional

Mutable

The binding protocol to be used for the logout response. Options are HTTP_REDIRECT or HTTP_POST. The default is HTTP_POST; existing configurations with no data default to HTTP_POST. This is an optional property.

sloEndpoint

String

Optional

Mutable

The logout endpoint URL. This is an optional property. However, if a sloEndpoint logout endpoint URL is not defined, logout actions result in an error.

sloResponseEndpoint

String

Optional

Mutable

The endpoint URL to submit the logout response. If a value is not provided, the sloEndpoint property value is used to submit SLO response.

sloWindow

Integer

Optional

Mutable

Defines how long PingOne can exchange logout messages with the application, specifically a LogoutRequest from the application, since the initial request. PingOne can also send a LogoutRequest to the application when a single logout is initiated by the user from other session participants, such as an application or identity provider. This setting is per application. The SLO logout is separate from the user session logout that revokes all tokens.

spEncryption

Object

Optional

Mutable

Enables PingOne to encrypt SAML assertions to be sent to the application. Assertions are not encrypted by default.

spEncryption.algorithm

String

Required

Mutable

The algorithm for encrypting the assertions (AES_128, AES_256, or TRIPLEDES).

spEncryption.certificate

Object

Required

Mutable

Contains the ID of the encryption public certificate that has been uploaded to PingOne.

spEncryption.certificate.id

String

Required

Mutable

The unique identifier of the encryption public certificate that has been uploaded to PingOne.

spEntityId

String

Required

Immutable

The service provider entity ID used to lookup the application. This must be unique within the environment.

spVerification.authnRequestSigned

Boolean

Optional

Mutable

Whether the Authn Request signing should be enforced. Default is false.

spVerification.certificates[].id

String[]

Optional

Mutable

An array that specifies the certificate IDs used to verify the service provider signature.

template

Object

Optional

Mutable

Valid only when the application type is TEMPLATE_APP. This identifies the application as integration in Integration Catalog.

template.configuration

Object

Required

Mutable

Contains a key/value map of the parameters required by the integration in Integration Catalog.

template.integration.id

String

Required

Mutable

The UUID of the integration in Integration Catalog.

template.version.id

String

Required

Mutable

The UUID of the integration version in Integration Catalog.

virtualServerIdSettings

Object

Optional

Mutable

Contains the virtual server ID or IDs to be used.

virtualServerIdSettings.enabled

Boolean

Optional

Mutable

Indicates whether the virtual server ID or IDs specified are to be used. Defaults to false.

virtualServerIdSettings.virtualServerIds

Object[]

Optional*

Mutable

*Required if enabled is true. Contains the list of virtual ID or IDs to be used.

virtualServerIdSettings.virtualServerIds.vsId

String

Optional*

Mutable

*Required if enabled is true. This must be a valid SAML entity ID.

virtualServerIdSettings.virtualServerIds.default

Boolean

Optional

Mutable

Indicates whether the virtual server identified by the associated vsId is to be used as the default virtual server.

Applications SAML metadata settings data model

Property Type Required? Mutable? Description

acsBindings

String

Optional

Mutable

The assertion consumer service binding protocol. Options are: HTTP_REDIRECT or HTTP_POST

acsUrls

String[]

Optional

Mutable

The assertion consumer service URLs.

authnRequestsSigned

Boolean

Optional

Mutable

Indicates whether the SAML authentication request is signed.

encryptionCertificate.pkcs7Der

Byte[]

Optional

Mutable

The PKCS7 encryption certificate in DER format.

sloBinding

String

Optional

Mutable

The SAML single logout binding protocol used for logout response. Options are: HTTP_REDIRECT or HTTP_POST.

sloEndpoint

String

Required

Mutable

The SAML single logout endpoint URL.

signingCertificates[].pkcs7Der

Byte[]

Optional

Mutable

The PKCS7 signing certificates in DER format.

Applications WS-Federation settings data model

These settings are for applications of type WEB_APP only, and are ignored for all other application types.
Property Type Required? Mutable? Description

assertionDuration

Integer

Optional

Mutable

The assertion validity duration in seconds. The default value is 300 seconds (5 minutes). Valid values are between 300 and 3932100.

audienceRestriction

String

Optional

Mutable

The service provider ID. Defaults to urn:federation:MicrosoftOnline.

corsSettings

Object

Optional

Mutable

Enables you to customize how the Authorization and Authentication APIs interact with CORS requests that reference the application. If omitted, the application allows CORS requests from any origin except for operations that expose sensitive information (such as, operations from /as/authorize and /as/token). We recommend you use corsSettings, rather than omitting this property.

corsSettings.behavior

String

Required

Mutable

Options are "ALLOW_NO_ORIGINS" and "ALLOW_SPECIFIC_ORIGINS". ALLOWS_NO_ORIGINS rejects all CORS requests. ALLOW_SPECIFIC_ORIGINS rejects all CORS requests except those listed in corsSettings.origins.

corsSettings.origins

String[]

Optional

Mutable

This must be specified when corsSettings.behavior is ALLOW_SPECIFIC_ORIGINS, and must be omitted or empty when corsSettings.behaviour is ALLOW_NO_ORIGINS. Limited to 20 values. The values are the origins from which CORS requests to the Authorization and Authentication APIs are allowed. Each value is an HTTP or HTTPS URL without a path. The host may be a domain name (including localhost), or an IPv4 address. Subdomains can be specified using the wildcard (*) to match any string.

domainName

String

Required

Mutable

The federated domain name (for example, the Azure custom domain).

idpSigning

Object

Required

Mutable

Contains the information about the signing of requests by the identity provider (IdP).

idpSigning.algorithm

String

Required

Mutable

The signature algorithm to be used for signing. Algorithms supported: SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withECDSA, SHA384withECDSA, and SHA512withECDSA.

idpSigning.key

String

Required

Mutable

The key pair to be used by the IdP to sign requests. If this isn’t specified, the default signing certificate for the environment is used.

idpSigning.key.id

String

Required

Mutable

The ID of the key specified for idpSigning.key.

kerberos

Object

Optional

Mutable

Contains the Kerberos authentication settings. Set this to null to disable Kerberos authentication.

kerberos.gateways

Object[]

Optional

Mutable

Contains the gateway properties.

kerberos.gateways.id

String

Required

Mutable

The UUID of the LDAP gateway.

kerberos.gateways.type

String

Required

Mutable

The gateway type. This must be "LDAP".

kerberos.gateways.userType.id

String

Required

Mutable

The UUID of a user type in the list of userTypes for the LDAP gateway.

replyUrl

String

Required

Mutable

The URL that the replying party (such as, Office365) uses to accept submissions of RequestSecurityTokenResponse messages that are a result of SSO requests.

sloEndpoint

String

Optional

Mutable

The single logout endpoint URL.

subjectNameIdentifierFormat

String

Optional

Mutable

The format to use for the SubjectNameIdentifier element. This value must be one of the following:

  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

wsTrustVersion

String

Optional

Mutable

The WS-Trust (Web Services Trust) version to use. Valid values are 1.2 and 1.3.

Applications WS-Federation settings data model for Microsoft Entra ID hybrid join

Hybrid join simplifies device management and allows organizations to join devices to on-premises Active Directory and the cloud with Entra ID.

Device authentication using hybrid join is available as a limited access release for customers who are licensed with PingOne for Workforce Plus or Premium in the North America region only and isn’t covered under standard Support service level agreements (SLAs). You can open support cases for feedback, bug reports, configuration questions, or other inquiries related, but resolution times for these cases will vary. These cases often require collaboration with our Engineering and Product teams, so response times might exceed the usual SLAs for your Support package.

Topics for this feature are draft documentation for limited access purposes only and aren’t complete or final.
Property Type Required? Mutable? Description

hybridJoinDeviceAttribute

String

Optional

Mutable

Required for Entra ID hybrid join. The value must be the name of a custom user attribute that an administrator has created. See Creating attributes and a population for hybrid joined devices for more information.

stsTokenType

String

Optional

Mutable

The type of token to use. Valid values:

  • http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1: Corresponds to SAML 1.1 in the admin console. Not suitable for Entra ID hybrid join.

  • urn:oasis:names:tc:SAML:1.0:assertion: Corresponds to SAML 1.1 for Office 365 in the admin console. Required for Entra ID hybrid join.

useMex13

Boolean

Optional

Mutable

Must be true to enable Entra ID hybrid join. After it’s set to true, update Entra ID to use the new metadata exchange endpoint. See Updating the federated IdP setting for more information.

Application events generated

Refer to Audit Reporting Events 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 do not have access to this resource.

403

You do not have permissions or are not licensed to make this request, or your license is exceeded.

404

The requested resource was not found.

500

An unexpected error occurred.

Use cases