Configures a Security Assertion Markup Language (SAML) identity provider (IdP).

Usage notes

During SAML 2.0-based single sign-on (SSO) logon, CloudSSO is an SP, and the identity management system of an enterprise is an IdP.

You can use one of the following methods to configure a SAML IdP. You can obtain the required metadata file or parameter values from your IdP.

  • Use the metadata file. You can specify the EncodedMetadataDocument parameter to upload the metadata file.
  • Manually configure the IdP. You can manually specifythe following parameters for your IdP: EntityId, LoginUrl, WantRequestSigned, and X509Certificate.

If you have configured a SAML IdP, the existing configurations are replaced after you call this operation.

  • If the IdP is configured by using the metadata file, all existing configurations are replaced with new configurations.
  • If the IdP is manually configured, the original parameter values that are different from the new parameter values are replaced.
Note If SSO logon is enabled, new configurations immediately take effect. Take note of the impacts on the production environment.

This topic provides an example on how to configure an IdP by using the metadata file within the directory d-00fc2p61****.

Limits

You can call this operation up to 100 times per second per account. This operation is globally limited to 100 times per second across all accounts. If the number of the calls per second exceeds a limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limits when you call this operation.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes SetExternalSAMLIdentityProvider

The operation that you want to perform. Set the value to SetExternalSAMLIdentityProvider.

DirectoryId String Yes d-00fc2p61****

The ID of the directory.

EncodedMetadataDocument String No PD94bWwgdmVyc2lvbj0iMS4****

The metadata file of the IdP. The value of this parameter is Base64-encoded.

The file is provided by the IdP that supports SAML 2.0.

SSOStatus String No Disabled

The status of SSO logon. Valid values:

  • Enabled
  • Disabled (default)
EntityId String No http://www.okta.com/exk3qwgtjhetR2Od****

The entity ID of the IdP.

LoginUrl String No https://dev-xxxxxx.okta.com/app/dev-xxxxxx_cloudssodemo_1/exk3qwgtjhetR2Od****/sso/saml

The logon URL of the IdP.

WantRequestSigned Boolean No false

Specifies whether CloudSSO needs to sign SAML requests. The requests are sent when users log on to the CloudSSO user portal to initiate SAML-based SSO. Valid values:

  • true: yes
  • false: no (default)
X509Certificate String No MIIC8DCCAdigAwIBAgIQP9eomUYGeoND****

The X.509 certificate in the PEM format. If you specify this parameter, all existing certificates are replaced.

For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Example Description
RequestId String 63160579-2E1B-57B0-8273-B27427172385

The ID of the request.

SAMLIdentityProviderConfiguration Object

The configurations of the IdP.

EntityId String http://www.okta.com/exk3qwgtjhetR2Od****

The entity ID of the IdP.

SSOStatus String Disabled

The status of SSO logon. Valid values:

  • Enabled
  • Disabled
DirectoryId String d-00fc2p61****

The ID of the directory.

EncodedMetadataDocument String PD94bWwgdmVyc2lvbj0iMS4****

The metadata file of the IdP. The value of this parameter is Base64-encoded.

CreateTime String 2021-11-10T02:57:16Z

The time when the IdP was configured for the first time.

WantRequestSigned Boolean false

Indicates whether CloudSSO needs to sign SAML requests. The requests are sent when users log on to the CloudSSO user portal to initiate SAML-based SSO. Valid values:

  • true: yes
  • false: no (default)
UpdateTime String 2021-11-10T02:57:16Z

The time when the IdP configurations were last modified.

CertificateIds Array of String [ "idp-c-00buzdx63z8ewtdf****", "idp-c-00gmuxnr2mrek3t2****" ]

The ID of the SAML signing certificate.

Multiple IDs are separated by commas (,).

LoginUrl String https://dev-xxxxxx.okta.com/app/dev-xxxxxx_cloudssodemo_1/exk3qwgtjhetR2Od****/sso/saml

The logon URL of the IdP.

Examples

Sample requests

https://[Endpoint]/?Action=SetExternalSAMLIdentityProvider
&DirectoryId=d-00fc2p61****
&EncodedMetadataDocument=PD94bWwgdmVyc2lvbj0iMS4****
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<SetExternalSAMLIdentityProviderResponse>
    <RequestId>63160579-2E1B-57B0-8273-B27427172385</RequestId>
    <SAMLIdentityProviderConfiguration>
        <EntityId>http://www.okta.com/exk3qwgtjhetR2Od****</EntityId>
        <SSOStatus>Disabled</SSOStatus>
        <DirectoryId>d-00fc2p61****</DirectoryId>
        <EncodedMetadataDocument>PD94bWwgdmVyc2lvbj0iMS4****</EncodedMetadataDocument>
        <CreateTime>2021-11-10T02:57:16Z</CreateTime>
        <WantRequestSigned>false</WantRequestSigned>
        <UpdateTime>2021-11-10T02:57:16Z</UpdateTime>
        <CertificateIds>idp-c-00buzdx63z8ewtdf****</CertificateIds>
        <CertificateIds>idp-c-00gmuxnr2mrek3t2****</CertificateIds>
        <LoginUrl>https://dev-xxxxxx.okta.com/app/dev-xxxxxx_cloudssodemo_1/exk3qwgtjhetR2Od****/sso/saml</LoginUrl>
    </SAMLIdentityProviderConfiguration>
</SetExternalSAMLIdentityProviderResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "63160579-2E1B-57B0-8273-B27427172385",
  "SAMLIdentityProviderConfiguration" : {
    "EntityId" : "http://www.okta.com/exk3qwgtjhetR2Od****",
    "SSOStatus" : "Disabled",
    "DirectoryId" : "d-00fc2p61****",
    "EncodedMetadataDocument" : "PD94bWwgdmVyc2lvbj0iMS4****",
    "CreateTime" : "2021-11-10T02:57:16Z",
    "WantRequestSigned" : false,
    "UpdateTime" : "2021-11-10T02:57:16Z",
    "CertificateIds" : [ "idp-c-00buzdx63z8ewtdf****", "idp-c-00gmuxnr2mrek3t2****" ],
    "LoginUrl" : "https://dev-xxxxxx.okta.com/app/dev-xxxxxx_cloudssodemo_1/exk3qwgtjhetR2Od****/sso/saml"
  }
}

Error codes

For a list of error codes, visit the API Error Center.