Configure an External Identity Provider (IdP)

API Documentation Disclaimer and Usage Guidance
The APIs described in this document are for illustrative purposes only. While efforts are made to keep this document current, always refer to Crosswork Assurance's official API documentation at https://api.accedian.io/iam-current.html for the authoritative source. Replace any example values in requests with those applicable to your environment.

Overview

Important: SP-Initiated SSO Only
Crosswork Assurance supports SP-Initiated SSO (Service Provider-Initiated Single Sign-On) only. IdP-Initiated SSO (Identity Provider-Initiated Single Sign-On) is not supported.
SP-Initiated SSO: The user starts the login process from login page. Crosswork Assurance redirects the user to the external IdP for authentication, then the IdP redirects back to Crosswork Assurance.
IdP-Initiated SSO: The user starts the login process directly from the IdP portal (not supported).
When configuring your external IdP (such as Okta, Azure AD, or other SAML providers), ensure that users access Crosswork Assurance through the login page rather than through an IdP-initiated portal link.

Currently, internal APIs (Skylight-AAA) and GUIs do not support configuring an external IdP on a {{variable.CPCA-short}} system. This topic explains how to configure an external IdP using exposed PCA APIs. SAML, OIDC, and LDAP are all supported as external IdP types

SAML support is available starting with aod-deployer version 25.7.215. LDAP and OIDC support require a later release and are not available on the 25.7.250 release line.

Provision an External IdP

Provisioning an external IdP is currently only possible using exposed APIs. SAML, OIDC, and LDAP are supported.
Note: LDAP and OIDC are not available on the 25.7.250 release line.

SAML Provisioning Steps:

1. Obtain the SAML IdP Metadata

Acquire the SAML IdP metadata either from a URL or an XML file.

URL example: https://mocksaml.com/api/saml/metadata

XML example:

Important: To support auto-linking with Crosswork Assurance users, the SAML metadata must include the following claim:

&lt;md:NameIDFormat&gt;
                urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
                &lt;/md:NameIDFormat&gt;

&lt;md:EntityDescriptor entityID="https://saml.example.com/entityid" validUntil="2035-12-02T16:11:14.390Z"&gt;
                &lt;md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"&gt;
                &lt;md:KeyDescriptor use="signing"&gt;
                &lt;ds:KeyInfo&gt;
                &lt;ds:X509Data&gt;
                &lt;ds:X509Certificate&gt;
                MIIC4jCCAcoCCQC33wnybT5QZDANBgkqhkiG9w0BAQsFADAyMQswCQYDVQQGEwJV SzEPMA0GA1UECgwGQm94eUhRMRIwEAYDVQQDDAlNb2NrIFNBTUwwIBcNMjIwMjI4 MjE0NjM4WhgPMzAyMTA3MDEyMTQ2MzhaMDIxCzAJBgNVBAYTAlVLMQ8wDQYDVQQK DAZCb3h5SFExEjAQBgNVBAMMCU1vY2sgU0FNTDCCASIwDQYJKoZIhvcNAQEBBQAD ggEPADCCAQoCggEBALGfYettMsct1T6tVUwTudNJH5Pnb9GGnkXi9Zw/e6x45DD0 RuRONbFlJ2T4RjAE/uG+AjXxXQ8o2SZfb9+GgmCHuTJFNgHoZ1nFVXCmb/Hg8Hpd 4vOAGXndixaReOiq3EH5XvpMjMkJ3+8+9VYMzMZOjkgQtAqO36eAFFfNKX7dTj3V pwLkvz6/KFCq8OAwY+AUi4eZm5J57D31GzjHwfjH9WTeX0MyndmnNB1qV75qQR3b 2/W5sGHRv+9AarggJkF+ptUkXoLtVA51wcfYm6hILptpde5FQC8RWY1YrswBWAEZ NfyrR4JeSweElNHg4NVOs4TwGjOPwWGqzTfgTlECAwEAATANBgkqhkiG9w0BAQsF AAOCAQEAAYRlYflSXAWoZpFfwNiCQVE5d9zZ0DPzNdWhAybXcTyMf0z5mDf6FWBW 5Gyoi9u3EMEDnzLcJNkwJAAc39Apa4I2/tml+Jy29dk8bTyX6m93ngmCgdLh5Za4 khuU3AM3L63g7VexCuO7kwkjh/+LqdcIXsVGO6XDfu2QOs1Xpe9zIzLpwm/RNYeX UjbSj5ce/jekpAw7qyVVL4xOyh8AtUW1ek3wIw1MJvEgEPt0d16oshWJpoS1OT8L r/22SvYEo3EmSGdTVGgk3x3s+A0qWAqTcyjr7Q4s/GKYRFfomGwz0TZ4Iw1ZN99M m0eo2USlSRTVl7QHRTuiuSThHpLKQQ==
                &lt;/ds:X509Certificate&gt;
                &lt;/ds:X509Data&gt;
                &lt;/ds:KeyInfo&gt;
                &lt;/md:KeyDescriptor&gt;
                &lt;md:NameIDFormat&gt;
                urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
                &lt;/md:NameIDFormat&gt;
                &lt;md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://mocksaml.com/api/saml/sso"/&gt;
                &lt;md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://mocksaml.com/api/saml/sso"/&gt;
                &lt;/md:IDPSSODescriptor&gt;
                &lt;/md:EntityDescriptor&gt;

Important: SP Details Required by Some IdPs
Some Identity Providers (such as Cisco Duo, Okta, or Azure AD) require you to provide Service Provider (SP) details—specifically the EntityID and ACS (Assertion Consumer Service) URLs—when creating the SAML application configuration. However, these SP details are only generated after you provision the SAML IdP in Crosswork Assurance.
Workaround: Use a temporary placeholder configuration (such as MockSAML) to initially create the SAML provider, then retrieve the actual SP details and update your IdP configuration.

Workaround: Using Placeholder Metadata to Retrieve SP Details

If your IdP requires SP details before you can obtain the metadata file, follow these steps:

Step A: Create the IdP with Placeholder Metadata

Use the MockSAML public metadata to initially provision the SAML IdP. This creates the provider in Zitadel and generates the required SP details.

curl --request POST \
  --url {baseUrl}/api/v3/idps/saml \
  --header 'content-type: multipart/form-data' \
  --header 'x-forwarded-tenant-id: ' \
  --form name=MyPlaceholderSAMLIdP \
  --form metadataUrl=https://mocksaml.com/api/saml/metadata

Note: Save the idpId returned in the response—you'll need it to update the configuration later.

Step B: Retrieve the EntityID and ACS URLs from Zitadel

After provisioning, log into the Zitadel interface to retrieve the SP details:

Access the Zitadel admin console for your deployment.
Select the pca Organization.
Navigate to Settings → Identity Providers.
Select the SAML Identity Provider you just created.
Expand the "WHAT NOW?" widget to reveal the SP details:
- EntityID (also called SP Entity ID or Issuer)
- ACS URL (Assertion Consumer Service URL)
- Metadata URL (optional, for IdPs that support metadata import)

Step C: Configure Your IdP with the Real SP Details

Return to your Identity Provider's admin console (Cisco Duo, Okta, Azure AD, etc.) and update the SAML application configuration with the actual EntityID and ACS URLs retrieved from Zitadel.

Once configured, download the updated SAML metadata file from your IdP.

Step D: Update the PCA IdP with Real Metadata

Use the PATCH endpoint to update the SAML IdP with your actual IdP's metadata:

curl --request PATCH \
  --url {baseUrl}/api/v3/idps/saml/{idpId} \
  --header 'content-type: multipart/form-data' \
  --header 'x-forwarded-tenant-id: ' \
  --form name=MyCiscoDuoSAMLIdP \
  --form metadataXmlFile=@{absolutePathToSamlMetadataFile}/cisco-duo-metadata.xml

Note: Replace {idpId} with the ID returned when you created the placeholder IdP, and update the file path to point to your actual IdP's metadata file.

2. Provision the External SAML IdP

Send a POST request to Crosswork Assurance as a user with skylight-admin or tenant-admin roles.

Note: Include either metadataUrl or metadataXmlFile in the Multipart Form body, but not both.

curl --request POST \
        --url {baseUrl}/api/v3/idps/saml \
        --header 'content-type: multipart/form-data' \
        --header 'x-forwarded-tenant-id: ' \
        --form name=MyFirstSAMLIdP \
        --form metadataXmlFile=@{absolutePathToSamlMetadataFile}/mock-saml-metadata.xml \
        --form metadataUrl=https://mocksaml.com/api/saml/metadata

Update an Existing SAML IdP

Use PATCH /api/v3/idps/saml/{id} to update an existing SAML IdP's name, metadata, or default status.

curl --request PATCH \
  --url {baseUrl}/api/v3/idps/saml/{idpId} \
  --header 'content-type: application/json' \
  --header 'x-forwarded-tenant-id: ' \
  --data '{
    "data": {
      "name": "UpdatedSAMLIdP",
      "isDefault": true
    }
  }'

Provision an OIDC IdP

Note: OIDC is not supported on the 25.7.250 release line. A later release is required.

Use POST /api/v3/idps/oidc to add an OIDC identity provider.

curl --request POST \
  --url {baseUrl}/api/v3/idps/oidc \
  --header 'content-type: application/json' \
  --header 'x-forwarded-tenant-id: ' \
  --data '{
    "data": {
      "name": "MyOIDCIdP",
      "isDefault": false,
      "config": {
        "oidc": {
          "issuer": "https://your-oidc-provider.example.com",
          "clientId": "your-client-id",
          "clientSecret": "your-client-secret"
        }
      }
    }
  }'

Use PATCH /api/v3/idps/oidc/{id} to update an existing OIDC IdP.

Provision an LDAP IdP

Note: LDAP is not supported on the 25.7.250 release line. A later release is required.

Use POST /api/v3/idps/ldap to add an LDAP identity provider.

curl --request POST \
  --url {baseUrl}/api/v3/idps/ldap \
  --header 'content-type: application/json' \
  --header 'x-forwarded-tenant-id: ' \
  --data '{
    "data": {
      "name": "MyLDAPIdP",
      "isDefault": false,
      "config": {
        "ldap": {
          "host": "ldap.example.com",
          "port": 636,
          "bindDn": "cn=admin,dc=example,dc=com",
          "bindPassword": "your-bind-password",
          "baseDn": "dc=example,dc=com",
          "userFilter": "(mail={login})"
        }
      }
    }
  }'

Use PATCH /api/v3/idps/ldap/{id} to update an existing LDAP IdP.

(Optional) Validate IdP Addition to Your Tenant

Confirm the IdP has been added by sending a GET request.

curl --request GET \
        --url {baseUrl}/api/v3/idps \
        --header 'x-forwarded-tenant-id: '

4. (Optional) Disable an Existing External IdP

Warning: Disabling an IdP affects all users associated with it. Currently, Crosswork Assurance does not provide an API to re-enable a disabled IdP.

Disable an IdP by sending a DELETE request.

curl --request DELETE \
  --url {baseUrl}/api/v3/idps/{idpId} \
  --header 'x-forwarded-tenant-id: '

Manage External IdP to User Associations

Note: These operations and UI screens require the tenant-admin role.

1. Add or Update External IdP Association for a User

Note: This PUT request replaces the entire list of external IdPs associated with the user.

Note: A user can have only one external IdP associated at any time.

curl --request PUT \
        --url {baseUrl}/api/v3/users/{userId}/idps \
        --header 'content-type: application/json' \
        --header 'x-forwarded-tenant-id: ' \
        --data '{
        "data": {
        "ids": [
        "{idpId}"
        ]
        }
        }'

2. (Optional) Validate External IdP Association with the User

curl --request GET \
        --url {baseUrl}/api/v3/users/{userId}/idps \
        --header 'x-forwarded-tenant-id: '

Get a Specific IdP by ID

curl --request GET \
  --url {baseUrl}/api/v3/idps/{idpId} \
  --header 'x-forwarded-tenant-id: '

(Optional) Remove External IdP Association with a User

curl --request PUT \
        --url {baseUrl}/api/v3/users/{userId}/idps \
        --header 'content-type: application/json' \
        --header 'x-forwarded-tenant-id: ' \
        --data '{
        "data": {
        "ids": []
        }
        }'

After removing a user's IdP association: The user can no longer log in via the external IdP. To allow them to set a local password, navigate to the user's detail page in the Crosswork Assurance UI and share the single-use Onboarding link with the user. This allows them to set a new local password and regain access.

When a user assigned to an external IdP enters their email on the login page, they are redirected to the respective IdP login page.

Reminder: All user provisioning must be done through the Crosswork Assurance UI or exposed Crosswork Assurance APIs to maintain user validity within the Crosswork Assurance system.

© 2026 Cisco and/or its affiliates. All rights reserved.

For more information about trademarks, please visit: Cisco trademarks
For more information about legal terms, please visit: Cisco legal terms

Documentation Index