Create SAML enterprise connection from customer provided metadata files

Knowledge Articles
, , , ,
1

Problem statement

I want to create a SAML SSO connection with client-provided metadata XML files.

Solution

Currently, this is only possible when using the Auth0 Management API, but not with the Dashboard GUI:

Depending on how your customer shares the metadata with you, there are two ways:

If your customer hosts the file on a publicly accessible URL, so you can specify this in the “metadataUrl” parameter for a new connection request:

curl --request POST \
  --url 'https://YOUR_DOMAIN/api/v2/connections' \
  --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataUrl": "YOUR_CUSTOMERS_METADATA_URL" } }'

Pass the metadata XML directly like this using “metadataXml”:

curl --request POST \
  --url 'https://YOUR_DOMAIN/api/v2/connections' \
  --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataXml": "<EntityDescriptor entityID='\''urn:saml-idp'\'' xmlns='\''urn:oasis:names:tc:SAML:2.0:metadata'\''>...</EntityDescriptor>" } }'

To call the Management API for your tenant, first, you will need to obtain a Management API token with the scope “create:connections”. Once you have a valid token, add it to the samples above where the placeholder MGMT_API_ACCESS_TOKEN is.
The below doc explains how to get a Management API token and create the connection endpoint you will be calling:

You can also use the Management API reference site (linked above) to make calls by clicking on the “SET API TOKEN” button in the top left will allow you to paste in a Management API token, and then you can enter the request parameters and call the endpoint using the TRY button for the relevant endpoint.

Once you have submitted this to the create connections endpoint, Auth0 will read the provided metadata, then create and configure the connection for you with the necessary parameters.