POST /api/v1/idps

Creates a new identity provider (IdP) integration.

SAML 2.0 IdP

You must first add the IdP's signature certificate to the IdP key store before you can add a SAML 2.0 IdP with a kid credential reference.

Don't use fromURI to automatically redirect a user to a particular app after successfully authenticating with a third-party IdP. Instead, use SAML deep links. Using fromURI isn't tested or supported. For more information about using deep links when signing users in using an SP-initiated flow, see Understanding SP-Initiated Login flow.

Use SAML deep links to automatically redirect the user to an app after successfully authenticating with a third-party IdP. To use deep links, assemble these three parts into a URL:

SP ACS URL
For example: https://${yourOktaDomain}/sso/saml2/:idpId
The app to which the user is automatically redirected after successfully authenticating with the IdP
For example: /app/:app-location/:appId/sso/saml
Optionally, if the app is an outbound SAML app, you can specify the relayState passed to it.
For example: ?RelayState=:anyUrlEncodedValue

The deep link for the above three parts is:
https://${yourOktaDomain}/sso/saml2/:idpId/app/:app-location/:appId/sso/saml?RelayState=:anyUrlEncodedValue

Smart Card X509 IdP

You must first add the IdP's server certificate to the IdP key store before you can add a Smart Card X509 IdP with a kid credential reference. You need to upload the whole trust chain as a single key using the Key Store API. Depending on the information stored in the smart card, select the proper template idpuser.subjectAltNameEmail or idpuser.subjectAltNameUpn.

Identity verification vendors as identity providers

Identity verification (IDV) vendors work like IdPs, with a few key differences. IDV vendors verify your user's identities by requiring them to submit a proof of identity. There are many ways to verify user identities. For example, a proof of identity can be a selfie to determine liveliness or it can be requiring users to submit a photo of their driver's license and matching that information with a database.

There are three IDV vendors (Persona, CLEAR Verified, and Incode) with specific configuration settings and another IDV vendor type (Custom IDV) that lets you create a custom IDV vendor, using a standardized IDV process. You can configure each of the IDV vendors as IdPs in your org by creating an account with the vendor, and then creating an IdP integration. Control how the IDVs verify your users by using Okta account management policy rules.

Persona
CLEAR Verified
Incode
Custom IDV

Servers

https://{yourOktaDomain}

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name Type Required Description

id

String

Unique key for the IdP

_links

Object

Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.

created

String

Timestamp when the object was created

issuerMode

String

Indicates whether Okta uses the original Okta org domain URL or a custom domain URL in the request to the social IdP

Valid values:

"CUSTOM_URL"
"DYNAMIC"
"ORG_URL"

Default value: "DYNAMIC"

name

String

Unique name for the IdP

properties

Object

The properties in the IdP properties object vary depending on the IdP type

properties.aalValue

String

The authentication assurance level (AAL) value for the Login.gov IdP. See Add a Login.gov IdP. Applies to LOGINGOV and LOGINGOV_SANDBOX IdP types.

properties.additionalAmr[]

Array

The additional Assurance Methods References (AMR) values for Smart Card IdPs. Applies to X509 IdP type.

properties.inquiryTemplateId

String

Yes

The ID of the inquiry template from your Persona dashboard. The inquiry template always starts with itmpl. Applies to the IDV_PERSONA IdP type.

properties.ialValue

String

The type of identity verification (IAL) value for the Login.gov IdP. See Add a Login.gov IdP. Applies to LOGINGOV and LOGINGOV_SANDBOX IdP types.

properties.idvMetadata

Object

Metadata about the IDV vendor. Available only for IDV_STANDARD IdPs.

properties.idvMetadata.privacyPolicy

String

A URL that links to the privacy policy for the IDV vendor

properties.idvMetadata.termsOfUse

String

A URL that links to the terms of use for the IDV vendor

properties.idvMetadata.vendorDisplayName

String

The display name of the IDV vendor

protocol

IdP-specific protocol settings for endpoints, bindings, and algorithms used to connect with the IdP and validate messages

type

String

The IdP object's type property identifies the social or enterprise IdP used for authentication. Each IdP uses a specific protocol, therefore the protocol object must correspond with the IdP type. If the protocol is OAuth 2.0-based, the protocol object's scopes property must also correspond with the scopes supported by the IdP type. For policy actions supported by each IdP type, see IdP type policy actions.

Type	Description	Corresponding protocol	Corresponding protocol scopes
`AMAZON`	Amazon as the IdP	OpenID Connect	`profile`, `profile:user_id`
`APPLE`	Apple as the IdP	OpenID Connect	`names`, `email`, `openid`
`DISCORD`	Discord as the IdP	OAuth 2.0	`identify`, `email`
`FACEBOOK`	Facebook as the IdP	OAuth 2.0	`public_profile`, `email`
`GITHUB`	GitHub as the IdP	OAuth 2.0	`user`
`GITLAB`	GitLab as the IdP	OpenID Connect	`openid`, `read_user`, `profile`, `email`
`GOOGLE`	Google as the IdP	OpenID Connect	`openid`, `email`, `profile`
`IDV_PERSONA`	Persona as the IDV IdP	ID verification
`IDV_CLEAR`	CLEAR Verified as the IDV IdP	ID verification	`openid`, `profile`, `identity_assurance`
`IDV_INCODE`	Incode as the IDV IdP	ID verification	`openid`, `profile`, `identity_assurance`
`IDV_STANDARD`	Custom IDV as the IDV IdP	ID verification	`openid`, `profile`, `identity_assurance`
`LINKEDIN`	LinkedIn as the IdP	OAuth 2.0	`r_emailaddress`, `r_liteprofile`
`LOGINGOV`	Login.gov as the IdP	OpenID Connect	`email`, `profile`, `profile:name`
`LOGINGOV_SANDBOX`	Login.gov's identity sandbox as the IdP	OpenID Connect	`email`, `profile`, `profile:name`
`MICROSOFT`	Microsoft Enterprise SSO as the IdP	OpenID Connect	`openid`, `email`, `profile`, `https://graph.microsoft.com/User.Read`
`OIDC`	IdP that supports OpenID Connect	OpenID Connect	`openid`, `email`, `profile`
`PAYPAL`	Paypal as the IdP	OpenID Connect	`openid`, `email`, `profile`
`PAYPAL_SANDBOX`	Paypal Sandbox as the IdP	OpenID Connect	`openid`, `email`, `profile`
`SALESFORCE`	SalesForce as the IdP	OAuth 2.0	`id`, `email`, `profile`
`SAML2`	Enterprise IdP that supports the SAML 2.0 Web Browser SSO Profile	SAML 2.0
`SPOTIFY`	Spotify as the IdP	OpenID Connect	`user-read-email`, `user-read-private`
`X509`	Smart Card IdP	Mutual TLS
`XERO`	Xero as the IdP	OpenID Connect	`openid`, `profile`, `email`
`YAHOO`	Yahoo as the IdP	OpenID Connect	`openid`, `profile`, `email`
`YAHOOJP`	Yahoo Japan as the IdP	OpenID Connect	`openid`, `profile`, `email`
`OKTA_INTEGRATION`	IdP that supports the OpenID Connect Org2Org IdP	OpenID Connect	`openid`, `email`, `profile`

Valid values:

"APPLE"
"PAYPAL_SANDBOX"
"OIDC"
"YAHOO"
"FACEBOOK"
"SAML2"
"LINKEDIN"
"MICROSOFT"
"LOGINGOV_SANDBOX"
"GITHUB"
"IDV_STANDARD"
"XERO"
"GOOGLE"
"IDV_CLEAR"
"X509"
"SPOTIFY"
"YAHOOJP"
"GITLAB"
"IDV_PERSONA"
"OKTA_INTEGRATION"
"IDV_INCODE"
"AMAZON"
"LOGINGOV"
"PAYPAL"
"SALESFORCE"
"DISCORD"

status

String

Valid values:

"ACTIVE"
"INACTIVE"

lastUpdated

String

Timestamp when the object was last updated

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.