Create an Entity ID for SAML Connection in the form of a URL

Knowledge Articles
, ,
1

Problem statement

In Security Assertion Markup Language ( SAML), the Entity ID plays a critical role in identifying the different entities that are involved in the authentication and authorization flow.

Both the Service Provider (SP) and the Identity Provider ( IdP) are considered to be entities in a SAML transaction. Each of these is assigned a unique Entity ID, which plays several roles:

  • Uniqueness: the ID ensures that only the desired parties are involved in a SAML transaction
  • Routing: the ID ensures that messages are routed to the correct entity ( SP, IdP )
  • Metadata: contains information about the endpoints, keys, and other settings necessary for the secure exchange of SAML messages. Here, the Entity ID is used to associate the SP or IdP with its corresponding set of metadata
  • Configuration: the ID performs an important role in the configuration of the SP and IdP, as it provides a unique identifier for each communicating entity

The Entity ID is frequently expressed in terms of a 'urn’ format. In an Auth0 context, the common structure for this is defined as follows:

urn:auth0:YOUR_TENANT:YOUR_CONNECTION_NAME

However, there may be occasions when a particular service provider requires the Entity ID to be expressed in terms of a ‘url’ format. A common structure for this is as follows:

https://{yourTenantDomain}

This requirement gives rise to several frequently asked questions:

  1. Why does Auth0 express the Entity ID in a ‘urn’ format?
  2. How can the current URN-based entity ID be changed to use a URL format?
  3. Would changing the format of the Entity ID for one specific Enterprise connection in a tenant impact any of the other customer SAML connections?

Solution

1. Why does Auth0 express the Entity ID in a ‘urn’ format?

According to section 8.3.6 of the core SAML specification:

“The syntax of such an identifier is a URI of not more than 1024 characters in length. It is RECOMMENDED that a system entity use a URL containing its domain name to identify itself.”

So defining the Entity ID in terms of a ‘url’ format is a recommendation: it is not mandatory. The approach that Auth0 takes is to:

  • define the Entity ID in a ‘urn’ format by default
  • to give customers the alternative option of using a custom format, such as ‘url’

This provides maximum flexibility when integrating with a wide range of different application services.

2. How can the current URN-based entity ID be changed to use a URL format?

The default Entity ID in Auth0 has this structure:

urn:auth0:YOUR_TENANT:YOUR_CONNECTION_NAME

Within the connection, it is stored within the ‘connection.options.entityId’ property.

If a custom ‘url’ format is required for the Entity ID, this can be done when either:

  • the connection is first created
  • an existing connection is updated

Let us consider each of these cases.

a) Define when the connection is created
When creating a SAML IdP connection, it’s possible to specify a metadata document ( or provide a metadata-URL ) that contains the custom Entity ID, as described in this document.

First, get an access token for use with the Management API.

Option 1: Provide metadata document content. Here is an example that illustrates the structure of the call:

curl --request POST \
  --url 'https://{yourDomain}/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>" } }'

Option 2: Provide a metadata document URL : this is similar to Option 1, though only the metadata URL needs to be supplied. Here is an example that illustrates the structure of the call:

curl --request POST \
  --url 'https://{yourDomain}/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": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX"" } }'

b) Update an existing connection with the custom Entity ID

There may be occasions when it is necessary to update an existing SAML connection, in order to use a custom Entity ID. Follow these steps to perform this task:

  1. First, get an access token for use with the Management API.
  2. Then retrieve the current settings from the connection through a Get-a-Connection call. This will provide a record of the current connection settings.
  3. Use a PATCH call to Update the connection with the custom Entity ID data in the Options object field, as shown below.
{
"options": {
    "entityId": "THE URL ENTITY ID",
    ...
},
...

Be aware that when updating the Options parameter, the whole Options object will be overridden.

In order to prevent this from happening, make sure that the “options” object includes both any existing options AND the custom Entity ID.

After completing this task, once again retrieve the connection settings to ensure that the custom Entity ID is present and correct.

3. Impact of changing the Entity ID

If a custom Entity ID is enabled on a SAML connection, only those customers who use that connection will be affected by the change.

For example, let us assume that a tenant has 15 x SAML connections configured. If one connection is updated to use a custom Entity ID, only customers who use that connection will be impacted by the change. Customers that use the other 14 x SAML connections will not be affected.

Related References