Integration process in brief:
- Review configuration points for SAML integrations
- Determine attribute release requirements
- Determine SAML metadata requirements
- Open a ServiceNow ticket to request integration with the Login service
- Configure SAML integration components
- Test and troubleshoot
SAML Configuration Points
If you are not familiar with SAML, it may be helpful to review some resources on the Web for background.
SAML is an XML-based security standard composed of profiles and bindings; profiles specify message exchange and bindings specify transport mechanics. Secure message exchange has two characteristics:
- Confidentiality - only the two communicating parties can read the messages
- Integrity - the message sender and contents are verifiable
Messages are typically exchanged over a secure channel for confidentiality, though it is not strictly required since SAML supports encryption of the XML contents of messages using public key cryptography. Message authenticity is obtained exclusively via XML digital signatures. XML encryption and signatures require the two communicating parties (called relying parties in SAML parlance) to agree on the keys used to communicate. In the case of encryption, the sender encrypts the message with the recipient’s public key, which ensures that the message can only be read by recipient by decrypting with his private key. In the case of signature, the message is signed with the sender’s private key and verified by the recipient using her published public key. Thus in all cases the sender must know the public key of the relying party with which it is communicating. In practice, public keys are specified as PEM-encoded X.509 certificates.
Required SAML Metadata Elements
Discovery is a key aspect of SAML ecosystems in practice. Services don’t have to explicitly know about each other; they simply need to agree on one or more locations where they can look up key information (credentials, endpoint URLs) needed to communicate with partners. SAML metadata is simply a structured XML document that lists all relying parties by unique identifier and specifies the services offered by each party. Parties consume the metadata to learn about other parties with which they may communicate.
All metadata entries begin with an EntityDescriptor that takes a single required attribute, entityID, which is simply a unique name by which the relying party is known to other members of the metadata group. Entity IDs are typically of the form https://service.subdomain.vt.edu/shibboleth. There are two principal types of SAML entity:
- Identity provider (IdP)
- Service provider (SP)
The Middleware group provides a single logical IdP that is backed by the Enterprise Directory for authentication and attribute release. Service providers make authentication requests to the the IdP. All SAML integrations for the purpose of this document are service providers. Every SP entity must declare one SPSSODescriptor element that contains the following:
- At least one KeyDescriptor element containing a PEM-encoded X.509 certificate whose public key is used for signing SAML messages.
- At least two AssertionConsumerService (ACS) elements with the specified bindings:
We recommend using self-signed certificates with validity periods of 5-10 years for all SAML metadata use cases. You SHOULD NOT use a Web server TLS certificate in SAML metadata. Note that all certificate metadata fields are ignored, including validitiy period; the certificate is merely a convenient container for the public key.
Optional SAML Metadata Elements
WantAssertionsSigned (uncommon) An attribute of EntityDescriptor that indicates that SAML assertions should be signed. SAML responses are signed by default, and that is typically what most relying parties expect. If assertion signing is enabled, it’s typically also required to disable response signing for the relying party in IdP configuration. Thus if this option is enabled, it typically requires coordination with IdP operators.
NameIDFormat (common) A SAML NameID in this context is the format of the principal ID of the subject of the SAML assertion. The default format, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent is a persistent, opaque, non-correlatable identifier that is “privacy preserving.” The default persistent ID format is guaranteed not to change for a given principal since it is derived from the Enterprise Directory uid element that has the same immutability guarantee.
The only other format supported by the IdP is urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName, which maps to the uupid (PID) Enterprise Directory attribute. This attribute is not strictly guaranteed to be immutable, but is loosely immutable and suitable for cases where the SP needs the username of the user as known to his home institution.
The IdP typically releases data about an authenticated user as part of the authentication protocol in order to support authorization and personalization at the SP. The following attributes are available for release:
|Attribute ID||Description||SAML 2 Encoding|
|accountState||User account state, e.g. ACTIVE, EXPIRED||urn:mace:vt.edu:ed:attribute-def:accountState|
|authId||Username with which user authenticated||urn:mace:vt.edu:ed:attribute-def:authId|
|displayName||Preferred display name, typically First M Last||urn:oid:2.16.840.1.1137220.127.116.11|
|eduPersonAffiliation||List of eduPerson affiliation, e.g. faculty, staff, student||urn:oid:18.104.22.168.4.1.5922.214.171.124.1|
|eduPersonEntitlement||Entitlements granted to user by SP||urn:oid:126.96.36.199.4.1.59188.8.131.52.7|
|eduPersonPrimaryAffiliation||Meaningless at present||urn:oid:184.108.40.206.4.1.59220.127.116.11.5|
|eduPersonScopedAffiliation||List of scoped eduPerson affiliations, e.g. firstname.lastname@example.org||urn:oid:18.104.22.168.4.1.5922.214.171.124.9|
|eduPersonPrincipalName||Scoped username, i.e. email@example.com||urn:oid:126.96.36.199.4.1.59188.8.131.52.6|
|eduPersonTargetedID||Targeted ID aka Persistent at present||urn:oid:184.108.40.206.4.1.59220.127.116.11.10|
|givenName||Given name (first name)||urn:oid:18.104.22.168|
|groupMembership||DNs of Enterprise Directory groups to which user belongs||urn:mace:vt.edu:ed:attribute-def:groupMembership|
|groupMembershipUugid||Group name (uugid) of ED groups to which user belongs||urn:mace:vt.edu:ed:attribute-def:groupMembershipUugid|
|loa||Virginia Tech level of identity assurance||urn:mace:vt.edu:ed:attribute-def:loa|
|Preferred email address||urn:oid:0.9.2342.19200300.100.1.3|
|passwordState||User account password state, e.g. ACTIVE, EXPIRED||urn:mace:vt.edu:ed:attribute-def:passwordState|
|passwordExpirationDate||User account password expiration date||urn:mace:vt.edu:ed:attribute-def:passwordExpirationDate|
|personType||Person type, e.g. “Virginia Tech” or “Guest”||urn:mace:vt.edu:ed:attribute-def:personType|
|sn||Surname (last name)||urn:oid:22.214.171.124|
|UDC_IDENTIFIER||Banner UDC identifier (BEIS)||urn:mace:vt.edu:ed:attribute-def:udcIdentifier|
|uid||Immutable numeric identifier for person||urn:oid:0.9.2342.19200300.100.1.1|
|uupid||Enterprise directory uupid attribute; not defined for guests||urn:mace:vt.edu:ed:attribute-def:uupid|
|virginiaTechAffiliation||Virginia Tech affiliations, e.g. VT_FACULTY, VT_STUDENT_ACTIVE||urn:mace:vt.edu:ed:attribute-def:virginiaTechAffiliation|
|virginiaTechID||Virginia Tech student/employee ID number, aka “9-number”||urn:mace:vt.edu:ed:attribute-def:virginiaTechID|
Mapping virginiaTechAffiliation onto eduPersonAffiliation
The vocabulary of the eduPersonAffiliation and eduPersonScopedAffiliation attributes follow a known vocabulary that is derived from VT affiliations according to the following mapping:
|VT Affiliation||eduPerson Affiliation(s)|
|VT-STAFF||staff, employee, member|
|VT-FACULTY||faculty, employee, member|
Any VT affiliations not mentioned in the above mapping are ignored and not released.
Attribute Release Policy
The attributes above are organized into bundles or groups of one or more attributes that may be requested by an SP. Bundles have a friendly name and a URI that drives the underlying attribute release machinery. The following bundles are available:
|R&S||http://id.incommon.org/category/research-and-scholarship||displayName, eduPersonAffiliation, eduPersonPrincipalName, givenName, mail, sn|
|EDAUTH||http://login.vt.edu/attribute/bundle/edauth||accountState, authId, eduPersonAffiliation, eduPersonPrimaryAffiliation, eduPersonPrincipalName, groupMembership, groupMembershipUugid, loa, passwordState, passwordExpirationDate, personType, UDC_IDENTIFIER, uid, uupid, virginiaTechAffiliation|
The following attributes are released to all known relying parties:
The R&S bundle is released to all InCommon service providers for faculty and staff at Virginia Tech; note that R&S attributes are not released to InCommon for students. That policy aspect regularly causes integration problems for graduate students attempting to use InCommon services oriented toward research that Virginia Tech does not have explicit relationships with.
If your service has special attribute release requirements not met by any of the above bundles, then the SSO integration will be costly in terms of policy headaches, time, and effort. While special cases are impossible, we strongly encourage using an existing bundle where possible.
There are two distinct integration routes for SAML services:
The choice of integration strategy is dictated by the service provider: they are either registered with InCommon or not. InCommon integrations typically go much smoother since the SAML metadata integration points are already defined in published InCommon metadata. If the service is not registered with InCommon, the second option is mandatory and requires services to specify the SAML integration parameters discussed above.
SAML Metadata Standard Support
We strongly encourage SPs support the metadata publish/subscribe capabilities discussed in the following standards document:
SPs that support metadata fetch and refresh can automatically detect and respond to configuration changes like key rollover and endpoint migration. Absent these capabilities, changes between IdP and SP need to be coordinated and when the SP is a third-party service provider the costs and complexities of coordination become infeasible if not impossible. In short, buy software and services that support the SAML metadata standard as a first-class capability and not an afterthought.
Requesting Integration with Login
A ServiceNow ticket must be opened if your SP has either of the following requirements:
- Attribute release policy configuration
- Metadata configuration
The former is needed for any SP for which Virginia Tech has a contract but is a member of InCommon, while both steps are typically required for non-InCommon services.
Please open a ServiceNow Ticket and include the following information:
- Service name and brief description
- SAML entity ID of service
- URL of published metadata or attach metadata file (for non-InCommon services)
- List of attribute bundles
Note that release of data to any third party MUST be approved by data stewards; the University Registrar is the data steward for student data. A contract that includes FERPA language is typically required to release directory data or FERPA-covered data for students.
SAML Integration Components
Middleware provides competent support for the most popular SAML integration library, the Shibboleth 2 Service Provider, which is available for both Apache and IIS platforms. The software consists of two components:
- Out-of-process service that handles SAML message processing
- Platform-specific Web server integration module that pipes messages into and out of the standalone SAML processor
The Shibboleth SP sits in front of the application and processes SAML messages as a prerequisite to accessing the underlying application. Upon successful authentication, the Shibboleth SP software sets request attributes that are accessible to the underlying application:
- Attributes (one for each ID as defined in attribute-map.xml)
For Apache there are three essential configuration files:
- Apache configuration file (shibboleth-sp/etc/shibboleth/apache2x.config)
- Shibboleth SP configuration file (shibboleth-sp/etc/shibboleth/shibboleth2.xml)
- Attribute mapping file (shibboleth-sp/etc/shibboleth/shibboleth2.xml)
The Apache configuration deals primarily with security policy configuration while the SP configuration deals with SAML-specific configuration bits.
A sample Apache configuration follows:
# Load the Shibboleth module. LoadModule mod_shib /apps/local/shibboleth-sp/lib/shibboleth/mod_shib_22.so # Used for example logo and style sheet in error templates. <IfModule mod_alias.c> <Location /shibboleth-sp> Allow from all </Location> Alias /shibboleth-sp/main.css /apps/local/shibboleth-sp/share/doc/shibboleth/main.css Alias /shibboleth-sp/logo.jpg /apps/local/shibboleth-sp/share/doc/shibboleth/logo.jpg </IfModule> <Location /secure> AuthType shibboleth ShibRequestSetting requireSession 1 # Uncomment to require 2-factor authentication #ShibRequestSetting authnContextClassRef http://login.vt.edu/ac/duo require valid-user </Location>
Vendor-specific SAML configuration
Many vendor products provide a GUI or configuration facility that generates SAML metadata from a simpler set of inputs. A configuration facility can be as simple as a single field for a base URL from which the entity ID and binding endpoint URLs are generated; signing and encryption certificates may be generated as well. In most cases the GUI facility simplifies configuration at the expense of control over every setting.