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 PCA’s official API documentation at https://api.accedian.io/session.html for the authoritative source. Replace any example values in requests with those applicable to your environment.

Overview

Currently, internal APIs (Skylight-AAA) and GUIs do not support configuring an external IdP on a ZITADEL PCA system. This topic explains how to configure an external IdP directly through the ZITADEL UI Console, assuming the user has admin privileges on their ZITADEL organization.

This feature is available starting with aod-deployer version 25.7.215.

Provision an External IdP

Provisioning an external IdP is currently only possible using exposed PCA APIs.  Only SAML is supported for setting up an external identity provider.

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 PCA users, the SAML metadata must include the following claim:

  <md:NameIDFormat>
                  urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
                  </md:NameIDFormat>

  <md:EntityDescriptor entityID="https://saml.example.com/entityid" validUntil="2035-12-02T16:11:14.390Z">
                  <md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
                  <md:KeyDescriptor use="signing">
                  <ds:KeyInfo>
                  <ds:X509Data>
                  <ds:X509Certificate>
                  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==
                  </ds:X509Certificate>
                  </ds:X509Data>
                  </ds:KeyInfo>
                  </md:KeyDescriptor>
                  <md:NameIDFormat>
                  urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
                  </md:NameIDFormat>
                  <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://mocksaml.com/api/saml/sso"/>
                  <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://mocksaml.com/api/saml/sso"/>
                  </md:IDPSSODescriptor>
                  </md:EntityDescriptor>

2. Provision the External SAML IdP  

Send a POST request to PCA 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 {baseUr}/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

3. (Optional) Validate IdP Addition to Your Tenant

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

curl --request GET \
        --url {baseUr}/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, PCA does not provide an API to re-enable a disabled IdP.

Disable an IdP by sending a DELETE request.

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

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 {baseUr}/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: '

3. (Optional) Remove External IdP Association with a User

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

Demo: External IdP Login Flow

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 PCA UI or exposed PCA APIs to maintain user validity within the PCA system.