Integration process in brief:

  1. Review configuration points for SAML integrations
  2. Determine attribute release requirements
  3. Determine SAML metadata requirements
  4. Open a ServiceNow ticket to request integration with the Login service
  5. Configure SAML integration components
  6. 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:

  1. Confidentiality - only the two communicating parties can read the messages
  2. 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:

  1. Identity provider (IdP)
  2. 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:

  1. At least one KeyDescriptor element containing a PEM-encoded X.509 certificate whose public key is used for signing SAML messages.
  2. At least two AssertionConsumerService (ACS) elements with the specified bindings:
    1. urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
    2. urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact

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.

Attribute Release

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.113730.3.1.241
eduPersonAffiliation List of eduPerson affiliation, e.g. faculty, staff, student urn:oid:1.3.6.1.4.1.5923.1.1.1.1
eduPersonEntitlement Entitlements granted to user by SP urn:oid:1.3.6.1.4.1.5923.1.1.1.7
eduPersonPrimaryAffiliation Meaningless at present urn:oid:1.3.6.1.4.1.5923.1.1.1.5
eduPersonScopedAffiliation List of scoped eduPerson affiliations, e.g. student@vt.edu urn:oid:1.3.6.1.4.1.5923.1.1.1.9
eduPersonPrincipalName Scoped username, i.e. pid@vt.edu urn:oid:1.3.6.1.4.1.5923.1.1.1.6
eduPersonTargetedID Targeted ID aka Persistent at present urn:oid:1.3.6.1.4.1.5923.1.1.1.10
givenName Given name (first name) urn:oid:2.5.4.42
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
mail Preferred email address urn:oid:0.9.2342.19200300.100.1.3
middleName Middle name urn:mace:vt.edu:ed:attribute-def:middleName
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:2.5.4.4
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-STUDENT-ENROLLED student, member
VT-EMPLOYEE-STATE employee, member
VT-EMPLOYEE-WAGE employee, member
VT-STUDENT-WAGE student, member
VT-STAFF staff, employee, member
VT-FACULTY faculty, employee, member
VT-ALUM alum
VT-STUDENT-FUTURE student
VT-STUDENT-RECENT affiliate
VT-EMPLOYEE-NON-STATE affiliate
VT-EMPLOYEE-PREHIRE affiliate
VT-EMPLOYEE-RETIREE affiliate
VT-EMPLOYEE-TEMPORARY affiliate
VT-EMPLOYEE-VOLUNTEER affiliate
VT-AFFILIATE-TEMPORARY affiliate

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:

Name URI Attributes
R&S http://id.incommon.org/category/research-and-scholarship displayName, eduPersonAffiliation, eduPersonPrincipalName, givenName, mail, sn
EPPN http://login.vt.edu/attribute/bundle/eppn eduPersonPrincipalName, uupid
EDAUTH http://login.vt.edu/attribute/bundle/edauth accountState, authId, eduPersonAffiliation, eduPersonPrimaryAffiliation, eduPersonPrincipalName, groupMembership, groupMembershipUugid, loa, passwordState, passwordExpirationDate, personType, UDC_IDENTIFIER, uid, uupid, virginiaTechAffiliation
UID http://login.vt.edu/attribute/bundle uid
VTID http://login.vt.edu/attribute/bundle/vtid virginiaTechID
GROUP http://login.vt.edu/attribute/bundle/group groupMembership, groupMembershipUugid
ENT http://login.vt.edu/attribute/bundle/entitlement eduPersonEntitlement

The following attributes are released to all known relying parties:

  1. eduPersonAffiliation
  2. eduPersonScopedAffiliation
  3. eduPersonTargetedID

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.

Special Cases

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.

Metadata Configuration

There are two distinct integration routes for SAML services:

  1. InCommon Federation View metadata
  2. Virginia Tech Institutional Metadata View metadata

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:

SAML Metadata Standard

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:

  1. Attribute release policy configuration
  2. 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:

  1. Service name and brief description
  2. SAML entity ID of service
  3. URL of published metadata or attach metadata file (for non-InCommon services)
  4. 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

Shibboleth SP

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:

  1. Out-of-process service that handles SAML message processing
  2. 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:

  1. Shib-Application-ID
  2. Shib-Session-ID
  3. Shib-Identity-Provider
  4. Shib-Authentication-Instant
  5. Shib-Authentication-Method
  6. Shib-AuthnContext-Class
  7. Shib-Session-Index
  8. Attributes (one for each ID as defined in attribute-map.xml)

For Apache there are three essential configuration files:

  1. Apache configuration file (shibboleth-sp/etc/shibboleth/apache2x.config)
  2. Shibboleth SP configuration file (shibboleth-sp/etc/shibboleth/shibboleth2.xml)
  3. 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.