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:
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
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
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
- 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
/shibbolethfor 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
/entityif 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
Every SAML entity, such as a Shibboleth identity provider or service provider, is identified by a unique
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
This kind of entity ID is strongly encouraged.
- An http scheme URI, of the form
- A urn scheme URI, of the form
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:
httpscheme entity IDs can be constructed on the basis of existing DNS domain names;
urnscheme URIs require use of a much more arcane registration hierarchy. If you believe you have a requirement for a
urnscheme URI then please contact the UK federation support team for advice.
- Another consequence of the different registration systems used is that
httpscheme entity IDs can be allocated by the owners of the entity being referred to, whereas
urnscheme IDs are normally allocated by a particular federation. Using
httpscheme 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
httpscheme entity IDs may make them more acceptable to other federations.
httpsscheme 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.
For historical reasons, the SDSS federation (forerunner to the UK federation) issued its own
urn scheme URIs for entity IDs. While all existing names of this type will remain valid in perpetuity, they are no longer used for new entities.
See also the Shibboleth recommendations on entity naming.