Versions Compared

Old Version 23

changes.mady.by.user trscavo@internet2.edu

Saved on

compared with

New Version Current

changes.mady.by.user trscavo@internet2.edu

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

An entity ID is a globally unique name given to for a SAML entity, either an Identity Provider (IdP) or a Service Provider (SP). The first step in configuring any permanent SAML deployment is to choose a permanent name for the entity. Please do so carefully and deliberately.

note MUST be a URI. It is strongly RECOMMENDED that an entity ID be a URL. If a site administrator submits metadata with some other form of entity ID, a manual vetting process is triggered, which may delay the approval process.
Tip
title
An entity ID

In particular, using URNs as entity IDs is NOT RECOMMENDED.

To summarize, InCommon will verify that all submitted entity IDs meet the following requirements:

  • An entity ID: 1) MUST be a URI, 2) SHOULD be a URL, and 3) SHOULD NOT be a URN.
  • The entity ID MUST be globally unique to avoid name collisions both within the Federation and across federations.

A common misconception is that the entity ID must match the endpoint locations for the deployment. This is not required and is often not the case. Unlike the endpoint locations, the entity ID accurately reflects the organization that owns the entity. Endpoint locations, on the other hand, are resolvable DNS names. An entity ID may or may not actually resolve to a web resource. (If it does, it is usually a page that describes the deployment.)

An entity ID is a persistent identifier for the entity. Make every effort to choose a permanent name for your deployment that will persist indefinitely.

Warning
titleDo NOT change your entity ID!

Once chosen, it is strongly recommended that you do not change the entity ID of an IdP or SP in metadata. Although this is possible to do in the current version of the Federation Manager (FM), future versions of the FM will not allow an existing entity ID to be changed.

...

vs. an endpoint location
Since an entity ID is a name, not a location, the entity ID and the endpoint locations in metadata do not need to match. If the entity ID is a URL (and it almost always is) it need not resolve.

The following sections give recommendations regarding entity naming within the InCommon Federation. For background information, review the general topic on entity naming in the Shibboleth 2 documentation.

IdP Naming

Historically, InCommon assigned an URN (Uniform Resource Name) to all new IdPs, based on the IdP's primary DNS domain name:

Code Block
languagexml
<EntityDescriptor entityID="urn:mace:incommon:example.edu">

However, InCommon no longer issues URNs to IdPs. The use of URNs as entity IDs for new IdPs (or any entity, for that matter) is strongly discouraged and in some situations not allowed.

For new IdPs registered in the Federation, InCommon recommends that URL-based entity IDs be used.

Note

If the IdP's entity ID is a URL (which is recommended), then:

  • the host part of the URL MUST be rooted in the organization's Primary DNS Domain
  • the URL MUST NOT contain a port number

For example, an IdP might have the following entity ID:

Code Block
languagexml
<EntityDescriptor entityID="https://idp_name.example.edu/idp">

...

As with IdPs, InCommon recommends that URL-based entity IDs be used in SP metadata.

Note

If the SP's entity ID is a URL (which is recommended), then:

  • the host part of the URL SHOULD be rooted in registered domain owned by the organization
  • the URL SHOULD NOT contain a port number

If either of these conditions is not met, a manual vetting process is triggered, which may delay the approval process.

For example, an SP might have the following entity ID:

Code Block
languagexml
<EntityDescriptor entityID="https://sp_name.example.edu/sp">

...

As with IdP naming, you MUST be prepared to commit to maintaining an SP entity ID essentially for the life of the service. Choose a name you can commit to maintaining even if the service will run at a different (or perhaps more than one) location independently of the endpoint locations, so if the latter change in the future. Remember, the entity ID and the endpoint location don't need to matchneed not change.

Info
titleNote

The following section is for site administrators registering new entities in InCommon.

Choosing a New Name

Below are some tips and suggestions that might be useful when choosing an entity ID. A short list of basic requirements is included at the end.

...

titleNote

...

An entity ID must be globally unique to avoid name collisions both within and across federations. To help ensure global uniqueness, an entity ID is almost always an absolute URL but it's important to note that an entity ID is a name, not a location. That is, an entity ID need not resolve to an actual web resource.

Note
titleRequirements for new entity IDs

Strict requirements:

  1. An entityID MUST be an absolute URI
  2. If the entityID is a URL, the host part of the URL MUST be a name rooted in a domain owned by the organization

Strong recommendations:

  1. An entityID SHOULD be an absolute URL starting with “https://” or “http://”
    1. The URL SHOULD NOT contain a port number, a query string, or a fragment identifier
    2. The host part of the URL SHOULD NOT contain the substring “www”
    3. The URL SHOULD NOT end with a slash (/)
  2. An entityID SHOULD NOT be more than 30 characters in length

If a site administrator submits metadata with an entity ID that does not meet the above requirements, a manual vetting process is triggered, which may delay the approval process.

A common misconception is that the entity ID must match the endpoint locations for the deployment. This is not required and is often not the case. Unlike the endpoint locations, the entity ID should accurately reflect the organization that owns the entity. Endpoint locations, on the other hand, are resolvable DNS names. An entity ID may or may not actually resolve to a web resource. (If it does, it is usually a page that describes the deployment.)

An entity ID is a persistent identifier for the entity. Make every effort to choose a permanent name for your deployment that will persist indefinitely.

Warning
titleDo NOT change your entity ID!

Once chosen, it is strongly recommended that you do not change the entity ID in metadata. Although this is possible to do in the current version of the Federation Manager (FM), future versions of the FM will not allow an existing entity ID to be changed.

Attempts to change an existing entity ID will trigger a potentially lengthy manual vetting process. Be prepared to explain why you think it is necessary to change your entity ID.

Below are some tips and suggestions that might be useful when choosing an entity ID.

Tips

  • include the substring "idp" or "identityprovider" in an IdP entity ID
  • include the substring "sp" or "serviceprovider" in an SP entity ID
  • do not include the substring "incommon" in an entity ID
  • do not include the name of your SAML software in an entity ID ("shibboleth", "adfs", "php", etc.)
  • an URL-based entity ID starting with "https://" is more flexible than one starting with "http://"
  • avoid using substring "www" in an URL-based entity ID
  • do not end an URL-based entity ID with a slash
    HTML
    (/)

Examples

IdP names:

...

  • https://webauth.example.edu/idp
  • HTMLhttps://its.example.edu/idp

SP names:

  • HTMLhttps://comanage.example.edu/sp
  • HTMLhttps://wiki.cs.example.eduorg/sphtml
  • https://intranet.math.example.edu/sp
  • https://myapp.example.com/sp

References

  • There is a general discussion of entity naming in the Shibboleth wiki