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 following three formats are supported:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (default, recommended)
The details of these formats are discussed in the SAML Name Identifiers section.
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.1137126.96.36.199|
|eduPersonAffiliation||List of eduPerson affiliation, e.g. faculty, staff, student||urn:oid:188.8.131.52.4.1.59184.108.40.206.1|
|eduPersonEntitlement||Entitlements granted to user by SP||urn:oid:220.127.116.11.4.1.5918.104.22.168.7|
|eduPersonPrimaryAffiliation||Meaningless at present||urn:oid:22.214.171.124.4.1.59126.96.36.199.5|
|eduPersonScopedAffiliation||List of scoped eduPerson affiliations, e.g. firstname.lastname@example.org||urn:oid:188.8.131.52.4.1.59184.108.40.206.9|
|eduPersonPrincipalName||Scoped username, i.e. email@example.com||urn:oid:220.127.116.11.4.1.5918.104.22.168.6|
|eduPersonTargetedID||Targeted ID aka Persistent at present||urn:oid:22.214.171.124.4.1.59126.96.36.199.10|
|givenName||Given name (first name)||urn:oid:188.8.131.52|
|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:184.108.40.206|
|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|
The following attribute are suitable for use as unique identifiers:
All the above attributes are available as SAML name identifiers as well as attributes to accommodate either case as required by relying party SAML software. The eduPersonTargetedID attribute is released to all known relying parties and is therefore the recommended attribute, though integration requirements may mandate use of uid, uupid, or virginiaTechID in order to correlate identities in the foreign system with Virginia Tech data elements. Daily batch processes are a common case where correlation with a convenient Virginia Tech identifier is required; student-oriented systems tend to require virginiaTechID despite its sensitive nature.
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.
SAML Name Identifiers
A SAML authentication response typically contains a section that identifies the name of the authenticated subject:
<saml2:Assertion ID="_f917230999120e7548e4c76b343c6ea6" IssueInstant="2017-05-15T11:51:43.247Z" Version="2.0" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"> <saml2:Issuer>https://example.com/idp</saml2:Issuer> <saml2:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" NameQualifier="https://example.com/idp" SPNameQualifier="https://example.com/sp" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">firstname.lastname@example.org</saml2:Nam eID> <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <saml2:SubjectConfirmationData Address="172.27.0.32" InResponseTo="_9a92b0bd7f7b44f994de4d473ab74973" NotOnOrAfter="2017-05-15T11:56:43.361Z" Recipient="https://example.com/sp/Shibboleth.sso/SAML2/POST"/> </saml2:SubjectConfirmation> </saml2:Subject> ... </saml2:Assertion>
Thus the assertion is about the subject email@example.com in the example above. Note that the format is declared as emailAddress, which may be specified by the requester. The following formats are supported by the Login Service:
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (default, recommended)
All name identifiers are based on person attributes that are invariant by policy or practice and are therefore suitable for using to consistently identify the same subject. The formats are discussed in further detail in following sections.
A persistent identifier is the default and is used when the relying party does not indicate a particular format. Persistent identifiers have the following characteristics:
- Unique per relying party
Persistent identifiers are always available regardless of release policy since they have excellent privacy qualities. On balance they suffer from poor usability and are not well-suited to displaying to users or for data correlation between Virginia Tech an the foreign system. They are implemented as a salted hash of the person uid and the relying party entity ID.
Email Address Format
The email address format produces an identifier that looks like an email address but is actually a scoped unique identifier where the unique ID and scope are separated by the ‘@’ character. The following attributes are available in order of precedence as email-formatted name identifiers:
Which attribute is used depends on the attribute release policy in effect. The following table indicates which attribute is used as a function of attribute release policies in effect.
|Email Format Attribute||Release Policies|
|uid||UID, VTID, EPPN|
|uid||UID, VTID, EPPN, R&S|
|uid||UID, VTID, R&S|
In the case where no source attribute is available to be released to the relying party, a NameID element is not produced (which is valid by the SAML protocol). If the relying party requires a NameID element, then it is the responsibility of the integrator to choose the persistent format or to ensure that the relying party has sufficient access to the required attribute via applicable release policy.
Windows Domain Format
This format is appropriate when the name identifier MUST be the Virginia Tech PID attribute. In order for this format to work correctly, the EPPN release policy MUST be in effect for the relying party, otherwise no NameID element will be produced in the SAML response.
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.