entityID Policy

Background

The primary purpose of the entityID is as a unique name or identifier for an entity. It is a URI (Uniform resource Indicator).

The URI does not have to resolve to an actual web page. Some deployers place metadata about the entity at this location. However, the UK federation recommends that metadata about the entity is obtained from us. This is because the UK federation runs an extensive range of checks on entities' metadata; we annotate the entities' metadata to provide additional information to relying parties; and a third party metadata service such as ours facilitates seamless transitions across configuration changes.

Summary of Policy

If this entity already has a validly allocated entityID, you should use that ID in the UK federation. (Ideally, an entity should be known under the same entityID in all federations in which it participates.)

If the entity does not already have a validly allocated entityID, you should construct an https scheme URI based on some DNS domain in your possession, such as a service-specific subdomain of your institutional domain name, or the DNS name of the machine hosting the service in question, followed by '/shibboleth' (or '/entity' to be software-neutral). The domain name component of the URI should be lower case. Examples:

https://idp.example.org/shibboleth

https://sp.server.org/shibboleth

https://idp.example.org/entity

https://sp.server.org/entity

While the entityID does not need to contain 'idp' or 'sp', this can be a useful naming convention. The intention is for the entity ID to be descriptive and concise.

Ownership of the domain name in a `https` or `http` scheme URI

If your organisation does not own the domain name that you wish to register in the entityID then the organisation that does own the domain name must grant permission to use it.

For domain names used in IdP entityIDs, please see our documentation on outsourcing IdPs.

The organisation granting permission to use a domain name in a SP registration must be a legal entity, and must send a letter of permission to the UK federation operator granting use of the domain name. This permission is granted for one or more specified entityIDs.

For certain closely-related organizations, we are prepared to accept a more general form of the domain permission letter which grants permission for all entityIDs containing a particular domain name to be used in SP registrations. As before, the organisation granting the permission must be a legal entity. This form of domain permission is for organisations that span multiple legal entities, for example where the organisation registering the entities is separate from the organisation that registers the domain names.

Recommended form of entityID

The UK federation recommends that entityIDs are constructed using the https scheme, as follows:

Start with https://
Add the domain name for your service or machine. Prefer the domain name for the service if it is likely to be migrated across physical machines over time.
Add an identifying path to complete the URI; conventionally this would be /shibboleth for a Shibboleth entity, but you can choose any path which, if the entity ID were regarded as a URL, would not currently resolve to an existing file. This allows you to place a copy of the metadata for your entity at that location at a later date, for dynamic metadata discovery. You could use something like /entity if your software is not Shibboleth, or if you want the entity ID to be software-neutral.

If your entity has no existing validly allocated entityID, the UK federation prefers that you construct an https scheme URI for this purpose.

The UK federation further recommends that the following are avoided in entityIDs, because (although they are not invalid as such), they do not make a useful contribution to the entityID's primary function, which is as an identifier:

port numbers, because they are superfluous in something that isn't being used as a location
machine names rather than service names in the domain name part, because that may cause trouble if the service moves to a new server
very long path names when they don't serve to distinguish between multiple identifiers

Rationale

Every SAML entity, such as a Shibboleth identity provider or service provider, is identified by a unique entityID. The entityID is used by entities to refer to themselves during communications, and to look up metadata for other entities.

It is highly desirable that an entity is referred to by the same name in every SAML federation in which it participates, both to simplify configuration and to allow free movement of entities from one federation to another. Allocating multiple names for the same entity should be avoided wherever possible, and to that end the UK federation has a policy of always preferring existing entity IDs for new entities to the federation, as long as they have been validly allocated.

Entity IDs are always URIs. At present, the UK federation accepts the following kinds of entity ID:

An https scheme URI, of the form https://domain.name/path
Example: https://idp.example.org/shibboleth
This kind of entity ID is strongly encouraged.
An http scheme URI, of the form http://domain.name/path
Example: http://idp.example.org/shibboleth
A urn scheme URI, of the form urn:valid:urn:allocation
Example: urn:mace:inqueue:sp.example.org

The federation's order of preference for the entity ID URI scheme is (1) https, (2) http, (3) urn. This is for the following reasons:

Valid https and http scheme entity IDs can be constructed on the basis of existing DNS domain names; urn scheme URIs require use of a much more arcane registration hierarchy. If you believe you have a requirement for a urn scheme URI then please contact the UK federation support team for advice.
Another consequence of the different registration systems used is that https and http scheme entity IDs can be allocated by the owners of the entity being referred to, whereas urn scheme IDs are normally allocated by a particular federation. Using https or http scheme entity IDs therefore assists in dispelling the false notion that an entity ID is, or should be, specific to a particular federation.
The lack of federation-specific components in https and http scheme entity IDs may make them more acceptable to other federations.
https scheme entity IDs can be constructed to be compatible with alternative metadata publishing schemes, such as that described in section 4.1 of the SAML 2.0 metadata specification.