The University of Strathclyde has a local federation, resources for which are available here.
Operation of the federation requires all member Identity Providers and Service Providers to each obtain federation metadata. IdPs require different metadata to SPs.
The metdata to be consumed by SPs is published at:
Checksums are available:
Service Providers should download the metadata file regularly, and where possible it should be verified against one of the checksums. The metadata for SPs only contains information about IdPs in the federation, so it rarely changes; a refresh every week or so should probably be sufficient.
(Any emergency updates required will be explicitly notified to SP operators).
An example bourne shell script is provided, it requires wget but is easily tweaked to use other tools.
An init.d script for Solaris is provided. Installation instructions are at the top. (I suppose these days on modern Solaris, we should be using SMF, but old habits die hard ...).
The metdata to be consumed by IdPs is published at:
Checksums are available:
Identity Providers should download the metadata file regularly, and where possible it should be verified against one of the checksums. The metadata for IdPs contains information about SPs in the federatiomn, which changes everytime an SP is added/changed/deleted, so it should be updated reasonably often, probably once per day.
A sample shibboleth2.xml is available. This is based on a working config, with some redundant stuff removed, and extra comments added. For most simple applications, especially those running Apache, this should be sufficient. Install it, then make the changes directed. More complicated installations may wish to refer to the default in the software distribution version.
You must ensure your server is time-synced using NTP.
In order to add the SP to the federation, the following information must be provided:
| Name | Description |
|---|---|
| hostname | The DNS name of an IP address on the system. Could be the DNS name associated with a service IP address, rather than the actual system's base DNS name; see entityId. |
| entityId | The entityId is a handle that uniquely identifies the SP. It is usually in the form of a URI containing a hostname as above, for example http://ho.st.na.me/shibboleth. If a system is operating more than one SP instance, then each instance will need its own entityId, so rather than using "...../shibboleth", you might use a name indicating the particular SP function instead, or else use a different DNS names per service. |
| Organisation Name | Will usually be something like "University of Strathclyde Department of Mathematics and Statistics" |
| Organisation URL | A web address for some information about the organisation, or possibly the service itself |
| Support contact name and email | The name and email address of the appropriate contact for support for the SP |
| Tech contact name and email | The name and email address of the appropriate contact for technical support for the SP. Likely to be the same as the Support contacts. |
| X.509 certificate | The contents of the certificate that will be used to encrypt transactions between this SP and the IdP. Upon installation of the SP software, a self-signed certificate is usually generated, often in the file sp-cert.pem: it is the contents of this file that are required. |
| Attributes required | A list of the attributes that are required to be released by the IdP in order for the SP to operate (see below for the available ones). In some cases, justification for the requirement may be needed. |
Note on entityId URI resolution: The URI that is the entityId does not need to be resolvable to a web-accessible object (i.e., used as a URL), but it may be convenient to have it operate as such to provide information about the service.
Note on entityId URI permanence: Since the entityId is the token by which this SP is referenced, it should not change over the lifetime of the service provision; hence it should probably not include the system's actual base hostname which may change when the service is moved to different hardware. We recommend a service IP addresses is obtained for the service and bound as an additional IP address to the network interface, with an appropriate service-related DNS name. If this is not possible, then an additional service-related DNS name can be created to point to the base IP address of the host. The service-related DNS name will then be used in the entityId URI.
Note on contacts: Use of role email addresses is encouraged here, along with the project/departmental team name rather than named individuals. Bear in mind that the metadata is public information, there are no restrictions on who can fetch it. Hence, any names or email addresses in this file should be considered exposed to anyone on the Internet.
Note on X.509 certificate: There are usually two sets of keys/certificates in use: one is the user-facing SSL cert that is checked by the web browser; the other is the one the SP uses to talk to the IdP, which serves two purposes: to identify itself, and to encrypt the conversation. While it is possible to use the same cert for all purposes, general convention now seems to be use a generated self-signed cert for the backend communication between SP and IdP.
When initially testing, you may wish to alter shibd.logger as such:
log4j.rootCategory=DEBUG, shibd_log ...
to turn logging up.
There's a sample shibd.logger, but it isn't a lot different from the distributed one just now.
Typically, an IdP at another institution will only release eduPersonTargetedID by default. Further common attributes may be released by special arrangement, but care must be taken that personal data is not being transferred without the consent of the users.
For the University of Strathclyde IdP, by default, only eduPersonScopedAffiliation and eduPersonTargetedID are released; others attributes are able to be released to internal SPs, but they must be specifically requested.
Any additional attributes to be received must be configured in the acceptance policy, set in attribute-policy.xml, although the default distribution has a rule that allows any otherwise unmentioned ones to pass through without any transformations, which is usually what you want:
<!-- Catch-all that passes everything else through unmolested. -->
<afp:AttributeRule attributeID="*">
<afp:PermitValueRule xsi:type="ANY"/>
</afp:AttributeRule>
Attributes mentioned must also be defined and/or uncommented in attribute-map.xml. For the Strathclyde ones (strathAcUk prefixes), you will need to add extra lines for them (see below).
It has been observed that for the Windows SP, if you change attribute-map.xml, you need to perform an iisreset for the system to notice. Restarting the Shibboleth daemon isn't sufficient.
The IdP is able to release data in an appropriate attribute that is derivable from data stored in the DS Active Directory service to local service providers.
These are defined in the usual standard LDAP schemas, or one of the eduPerson schemas, and are exposed as Shibboleth attributes and available to SPs if permitted by the Attribute Release Policy.
| Name | Meaning |
|---|---|
| cn | Common name. We use the login username in 'cn', so will be of the form gbd08123 |
| sn | Surname (or family name) |
| title | Job title according to HR for a member of staff. Usually not present for students. |
| description | A composite field merging data from various other fields. For example: "staff-primary account, 500 MB H:Dr ive, PersonID=99999" |
| physicalDeliveryOfficeName | Room, building and campus, according to HR. For example: "9.99, mcdonald towers (ja campus)" |
| telephoneNumber | Full DDI telephone number. For example: "01415484000" |
| givenName | First name (Given name, Forename, Christian name) |
| initials | Initials of all but surname |
| displayName | Name, as preferentially displayed. As seen in Exchange address list, for example. |
| department | Name of primary department |
| Preferred/primary email name |
These are locally defined in Active Directory (see LDAP attributes), and are exposed as Shibboleth attributes and available to SPs if permitted by the Attribute Release Policy.
| Name | Meaning |
|---|---|
| strathAcUkPersonID | Unique integer key used in HR systems for this person. Each account owned by the same natural person should carry the same PersonId. Not present on role accounts, etc. |
| strathAcUkAccountCategory | A text string describing the classification of the account; see below for the enumeration of possible values. |
| strathAcUkAccountCategory string | Meaning |
|---|---|
| staff-primary | A member of University staff on Payroll. Also, those who obtain access via the Temp IT Access route (before May 2015). |
| staff-secondary | A secondary account allocated for someone who already has a staff-primary account. |
| undergraduate | Undergraduate student |
| postgraduate | Postgraduate taught student |
| postgraduate-research | Postgraduate research student |
| pre-registered | Classification of an account before formal registration has taken place |
| visitor(non-student) | |
| class/conference | Short-term accounts for specific classes, conferences or events. |
| external-student | Students with other institutions who are granted access to facilities. |
| limited-access | |
| it-access | Those who obtain access via the Temp IT Access route (after May 2015). |
| completed-student | Students who have completed their programme of study but are still known to the system. |
| other |
attribute-map.xml will need to be modified with extra lines; the following have been tested to work OK, as examples:
<Attribute
name="urn:mace:ac.uk:strath.ac.uk:dir:attribute-def:strathAcUkPersonID"
id="strathAcUkPersonID">
<AttributeDecoder xsi:type="StringAttributeDecoder"
caseSensitive="false"/>
</Attribute>
<Attribute
name="urn:oid:1.3.6.1.4.1.7577.10.1.2.10"
id="strathAcUkPersonID">
<AttributeDecoder xsi:type="StringAttributeDecoder"
caseSensitive="false"/>
</Attribute>
<Attribute
name="urn:mace:ac.uk:strath.ac.uk:dir:attribute-def:strathAcUkAccountCategory"
id="strathAcUkAccountCategory">
<AttributeDecoder xsi:type="StringAttributeDecoder"
caseSensitive="false"/>
</Attribute>
<Attribute
name="urn:oid:1.3.6.1.4.1.7577.10.1.2.13"
id="strathAcUkAccountCategory">
<AttributeDecoder xsi:type="StringAttributeDecoder"
caseSensitive="false"/>
</Attribute>
<Attribute
name="urn:mace:ac.uk:strath.ac.uk:dir:attribute-def:strathAcUkRegistrationNumber"
id="strathAcUkRegistrationNumber">
<AttributeDecoder xsi:type="StringAttributeDecoder"
caseSensitive="false"/>
</Attribute>
<Attribute
name="urn:oid:1.3.6.1.4.1.7577.10.1.2.11"
id="strathAcUkRegistrationNumber">
<AttributeDecoder xsi:type="StringAttributeDecoder"
caseSensitive="false"/>
</Attribute>
<Attribute name="urn:oid:2.5.4.3" id="cn"/> <Attribute name="urn:oid:2.16.840.113556.1.2.141" id="department"/>etc, in general, anywhere you are using an attribute which has the name of the form urn:mace:dir:attribute-def:..., you should also uncomment the equivalent urn:oid:... form line too. You will probably also want to add the the oid lines mentioned above for the strathAcUk attributes.
In addition, we can also provide assertions in the eduPersonEntitlement multi-valued attribute that can be calculated based on AD data. For example, we may be able to assert membership of a particular group (using the memberOf DS attribute). The assertions will take the form of a URN, usually a locally defined one from the Strathclyde URN registry namespace.
It is possible to add more data sources, such as SQL databases, that can be queried in order to generate attributes for SPs, however we currently do not do so.
If your application looks at the environment variable REMOTE_USER to determine the username (perhaps it was developed in an environment where the web server handled authentication and populates this field), then you can tell the Shibboleth SP which of the attributes received from the IdP to populate REMOTE_USER with.
In shibboleth2.xml, there is a section for settings relating to each application (in most cases you will just modify the ApplicationDefaults section):
<ApplicationDefaults id="default" policyId="default"
entityID="https://sp.example.org/shibboleth"
homeURL="https://sp.example.org/index.html"
REMOTE_USER="eppn persistent-id targeted-id"
signing="false" encryption="false"
...
Here, the first that exists of "eppn", "persistent-id" or "targeted-id" will be used to populate REMOTE_USER. These names are the ids defined in attribute-map.xml, for example:
<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
If, for example, you wanted your application to see the ITS usernumber in the environment variable REMOTE_USER, then you could request that the cn attribute be released to your SP, ensure it is defined in attribute-map.xml, then set:
REMOTE_USER="cn"
in the ApplicationDefaults clause.
However, note that the standard attribute eduPersonPrincipalName will contain the (scoped) username, see below.
Previous to 26th January 2010, eduPersonPrincipalName contained a value based on the LDAP mail field: i.e., a person's email address. Subsequently, this was changed to be based on DS usernumber, scoped with @strath.ac.uk. As well as hopefully subsequently remaining static for any particular user at that point (email addresses can and do change!), this will also provide a convenient means of accessing a person's usernumber. An application may chose to check the scope of the field, and if acceptable strip it off and use the remainder as the usernumber.
The eduPersonScopedAffiliation attribute contains one or more of a fixed set of values that describe the affiliation the authenticating user has with their institution. In general, SPs should first examine the values in this attribute to determine whether a user is permitted to access the application, based generally on the institution in the scope (e.g., @strath.ac.uk), and perhaps more specifically the nature of that affiliation. The most important values asserted in this attribute (all appended with @site.ac.uk) follow.
The formal definition for eduPersonAffiliation
The permitted values and their interpretation according to the Technical Recommendations for Particcipants, applicable to the UK Federation (see section 7.1.2.1).
| eduPersonScopedAffiliation string | Meaning |
|---|---|
| staff | User is a member of staff, which usually means they are on the payroll. |
| student | User is a registered student. |
| member | User is associated with the University, generally staff or student or someone else with a strong association. |
| affiliate | User is somehow associated with the University, in so far as we have a reason to give them an account, but their association isn't as strong as member. |
Most commercial SPs provide access to their services to any user who has been asserted as member (but not affiliate). Some may require the more specific assertion of student or staff.
For the IdP, the following algorithm applies, for generating the values of eduPersonScopedAffiliation:
The permitted values for the LDAP attribute strathAcUkAccountCategory are documented in LDAP attributes.
Other values for strathAcUkAccountCategory are ignored.
If you require a new attribute for middleware purposes, and cannot find a pre-existing one in one of the usual attribute sets (eduPerson, X.520), you should see the Strathclyde URN registry. Please do not invent your own names for attributes.