The Incommon Federation wiki has moved.

Please visit the new InCommon Federation Library wiki for updated content. Remember to update your bookmarks.

Click in the link above if you are not automatically redirected in 15 seconds.



You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 24 Next »

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

An entity ID 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.

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.

Do 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.

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.

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:

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

However, InCommon no longer issues URNs to IdPs. For new IdPs registered in the Federation, InCommon recommends that URL-based entity IDs be used.

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:

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

where idp_name is a carefully chosen, logical name for the IdP.

For those IdPs that already have an URN-based entity ID, InCommon strongly recommends that you do not change your entity ID to one that is URL-based. In fact, you should never change an IdP entity ID. Doing so will almost certainly cause service disruptions at partner SP sites. The user experience may be adversely affected as well (since discovery interfaces typically write cookies containing the IdP's entity ID).

SP Naming

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

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:

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

where sp_name is again a carefully chosen, logical name for the 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 in the future. Remember, the entity ID and the endpoint location don't need to match.

Choosing a 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.

Note

This section is primarily for new entities choosing a name for the first time. Existing entities may want to skim this section for future reference but the above comments regarding name consistency take precedence.

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
  • 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 (/)

Examples

IdP names:

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

SP names:

  • https://comanage.example.edu/sp
  • https://wiki.cs.example.edu/sp
  • https://intranet.math.example.edu/sp
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels