Login Service SAML Protocol Integration

Introduction

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 Integration Coordinates

The following configuration points are vital for most integrations and are listed here for quick reference.

Metadata Sources

The Login Service supports two metadata sources:

  1. InCommon Federation (>50MB)
  2. Virginia Tech

Entity IDs

The entity ID for our IdP (login.vt.edu) varies by SAML metadata source and tier:

Metadata Source Tier Entity ID
InCommon prod urn:mace:incommon:vt.edu
InCommon pprd https://shib-pprd.middleware.vt.edu
VT prod https://shib.vt.edu
VT pprd https://shib-pprd.middleware.vt.edu
VT dev https://shib-dev.middleware.vt.edu

Certificates

The following signing certificates are required by service providers in order to verify digital signatures on SAML response messages sent by our IdP. The certificates are listed by entity ID, which as noted above varies with SAML metadata source and tier.

urn:mace:incommon:vt.edu (InCommon prod)

MIIEETCCAvmgAwIBAgIJANFfZSukyEO/MA0GCSqGSIb3DQEBBQUAMIGeMQswCQYD VQQGEwJVUzERMA8GA1UECAwIVmlyZ2luaWExEzARBgNVBAcMCkJsYWNrc2J1cmcx PDA6BgNVBAoMM1ZpcmdpbmlhIFBvbHl0ZWNobmljIEluc3RpdHV0ZSBhbmQgU3Rh dGUgVW5pdmVyc2l0eTETMBEGA1UECwwKTWlkZGxld2FyZTEUMBIGA1UEAwwLc2hp Yi52dC5lZHUwHhcNMTUwNTE1MTIzNjUyWhcNMjAwNTE0MTIzNjUyWjCBnjELMAkG A1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApCbGFja3NidXJn MTwwOgYDVQQKDDNWaXJnaW5pYSBQb2x5dGVjaG5pYyBJbnN0aXR1dGUgYW5kIFN0 YXRlIFVuaXZlcnNpdHkxEzARBgNVBAsMCk1pZGRsZXdhcmUxFDASBgNVBAMMC3No aWIudnQuZWR1MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7NT6bMir XETWSQhI1Fr1Ppva6E/ZUfAlV0RLQ78cgGW5//JNoER3TwxpSVFkYupPOoatnC3k +6cfJmuib7JjtFizyqgXLNrLlEembZbECXHGR/+P9oUEWQhrAPjRz2ZugWpQRiFD dddD4uaJhigkeayFe7VNERg8QTaS+avQisuMOnHlnmpXOQi19PdY7+5auHwIgQ0y eSUKFaIwpwL8wx93r5JtHvIajJ4RjmWgtN1o4v0YR3RX3I4lspEXlmIPlOBv8d6k wicOB2WszBrVw6zTYEdXQ9j1IRKXqwmWCCYREFnHYzGjhcpptZPEYJJX90ke6ffF defssBhk/oc2bwIDAQABo1AwTjAdBgNVHQ4EFgQUzFhBa3OBEjb9liQHKAuWoUwo 5McwHwYDVR0jBBgwFoAUzFhBa3OBEjb9liQHKAuWoUwo5McwDAYDVR0TBAUwAwEB /zANBgkqhkiG9w0BAQUFAAOCAQEARVsLDVRz6xPx2hzIgNy7ro49tLERHmGyzK14 AkezGKhJA3q8371FgUpSTFu0pAcl6X6v2xJRb4CFhRxIpe+/xbEP2CznPUKybE3A I5NINQy6jlWXad5fYRohDI4m9ON39BO3MEIHKLm2FLHUXE0NmEWoyNeg+4cjZMK/ eTd7/azVGGJNAVKLfNaHHm1K1MVWtTK1Jt5QuG0iy2PZnKQOJ4c7RUrAHOqfg8TE 6Cq66ObNkIKPmivcU0uUy27IT9eM9Y/WyNfYY3isQqvLareyEiHQTeZniIwlq734 QYvy/+Jxoro0d/n+VkiOjSlrLIrprl9zVmvWjjPvpth13a2m1Q==

https://shib-pprd.middleware.vt.edu (InCommon pprd)

MIIEMTCCAxmgAwIBAgIJAKdWq5o75wFhMA0GCSqGSIb3DQEBBQUAMIGuMQswCQYD VQQGEwJVUzERMA8GA1UECAwIVmlyZ2luaWExEzARBgNVBAcMCkJsYWNrc2J1cmcx PDA6BgNVBAoMM1ZpcmdpbmlhIFBvbHl0ZWNobmljIEluc3RpdHV0ZSBhbmQgU3Rh dGUgVW5pdmVyc2l0eTETMBEGA1UECwwKTWlkZGxld2FyZTEkMCIGA1UEAwwbc2hp Yi1wcHJkLm1pZGRsZXdhcmUudnQuZWR1MB4XDTE1MDMzMTE3NTQ1MVoXDTIwMDMz MDE3NTQ1MVowga4xCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJnaW5pYTETMBEG A1UEBwwKQmxhY2tzYnVyZzE8MDoGA1UECgwzVmlyZ2luaWEgUG9seXRlY2huaWMg SW5zdGl0dXRlIGFuZCBTdGF0ZSBVbml2ZXJzaXR5MRMwEQYDVQQLDApNaWRkbGV3 YXJlMSQwIgYDVQQDDBtzaGliLXBwcmQubWlkZGxld2FyZS52dC5lZHUwggEiMA0G CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC115mM3qIxxFAoGkwjGvpmQGqi3NhN st418It0iG4BVZR8UrruBsGBbH69G3ggDTKGRgJNA5HDcdZZMuWXqiNOQfWNTweA pezxK941Ax1+tV5h0vbsx0JOGtMVabGYFcty/DNb9yu5XOLEc8aGQAxSusuU5WOp 1XS0b7TXJBQfjPywXGcOpcVl2+GedDmjEeVKmxjfoW/HklLZjn1gCrxsJOzIwnOx arbbc08ki97c5/Tu0BEvPeqSecOjRX2zlA3YHnPKvfj5lMRoD77az4RC4H8rNdE/ IAqQVYt90OeTVShMad4uR/c42me45Rx+LQSFKL+dShXxIYXCYuF35y7bAgMBAAGj UDBOMB0GA1UdDgQWBBRHBJo36Os/RfOmR7yWQDsxgiQF4jAfBgNVHSMEGDAWgBRH BJo36Os/RfOmR7yWQDsxgiQF4jAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUA A4IBAQBToc/vEzySf7dFQjLqWJpmGxZgFo5xoVP66XF0qPIqAMKR1LLToetmLA0l NeuY5HzcpcuD5ILAHc7IZB+5RFSam1yQIj8L9u/KZTr+sdgyNm2KDHGhEmTTUB63 JsAPDsCX8Uri2bGOk1JTnaNf/zTQxD4xD5tc/dsOUubw27xLX46LuN4w6GSvbQ+D RGfMNHwWfa0PXRqOMktEB4KRMimTVu7FfRX/NI8Qt1cMl0Ur/EKapBVy58SChwsS ekCkx5H2+ar5TQpn8MoyloboaroHeHtFlQxhUY6fJWjcvZke6hY0W9MMubaovizq AzGwzzUtK3/d7PxUuTm7H1vsPcEs

https://shib.vt.edu (VT prod)

MIIEETCCAvmgAwIBAgIJANFfZSukyEO/MA0GCSqGSIb3DQEBBQUAMIGeMQswCQYD VQQGEwJVUzERMA8GA1UECAwIVmlyZ2luaWExEzARBgNVBAcMCkJsYWNrc2J1cmcx PDA6BgNVBAoMM1ZpcmdpbmlhIFBvbHl0ZWNobmljIEluc3RpdHV0ZSBhbmQgU3Rh dGUgVW5pdmVyc2l0eTETMBEGA1UECwwKTWlkZGxld2FyZTEUMBIGA1UEAwwLc2hp Yi52dC5lZHUwHhcNMTUwNTE1MTIzNjUyWhcNMjAwNTE0MTIzNjUyWjCBnjELMAkG A1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYDVQQHDApCbGFja3NidXJn MTwwOgYDVQQKDDNWaXJnaW5pYSBQb2x5dGVjaG5pYyBJbnN0aXR1dGUgYW5kIFN0 YXRlIFVuaXZlcnNpdHkxEzARBgNVBAsMCk1pZGRsZXdhcmUxFDASBgNVBAMMC3No aWIudnQuZWR1MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7NT6bMir XETWSQhI1Fr1Ppva6E/ZUfAlV0RLQ78cgGW5//JNoER3TwxpSVFkYupPOoatnC3k +6cfJmuib7JjtFizyqgXLNrLlEembZbECXHGR/+P9oUEWQhrAPjRz2ZugWpQRiFD dddD4uaJhigkeayFe7VNERg8QTaS+avQisuMOnHlnmpXOQi19PdY7+5auHwIgQ0y eSUKFaIwpwL8wx93r5JtHvIajJ4RjmWgtN1o4v0YR3RX3I4lspEXlmIPlOBv8d6k wicOB2WszBrVw6zTYEdXQ9j1IRKXqwmWCCYREFnHYzGjhcpptZPEYJJX90ke6ffF defssBhk/oc2bwIDAQABo1AwTjAdBgNVHQ4EFgQUzFhBa3OBEjb9liQHKAuWoUwo 5McwHwYDVR0jBBgwFoAUzFhBa3OBEjb9liQHKAuWoUwo5McwDAYDVR0TBAUwAwEB /zANBgkqhkiG9w0BAQUFAAOCAQEARVsLDVRz6xPx2hzIgNy7ro49tLERHmGyzK14 AkezGKhJA3q8371FgUpSTFu0pAcl6X6v2xJRb4CFhRxIpe+/xbEP2CznPUKybE3A I5NINQy6jlWXad5fYRohDI4m9ON39BO3MEIHKLm2FLHUXE0NmEWoyNeg+4cjZMK/ eTd7/azVGGJNAVKLfNaHHm1K1MVWtTK1Jt5QuG0iy2PZnKQOJ4c7RUrAHOqfg8TE 6Cq66ObNkIKPmivcU0uUy27IT9eM9Y/WyNfYY3isQqvLareyEiHQTeZniIwlq734 QYvy/+Jxoro0d/n+VkiOjSlrLIrprl9zVmvWjjPvpth13a2m1Q==

https://shib-pprd.middleware.vt.edu (VT pprd)

MIIEMTCCAxmgAwIBAgIJAKdWq5o75wFhMA0GCSqGSIb3DQEBBQUAMIGuMQswCQYD VQQGEwJVUzERMA8GA1UECAwIVmlyZ2luaWExEzARBgNVBAcMCkJsYWNrc2J1cmcx PDA6BgNVBAoMM1ZpcmdpbmlhIFBvbHl0ZWNobmljIEluc3RpdHV0ZSBhbmQgU3Rh dGUgVW5pdmVyc2l0eTETMBEGA1UECwwKTWlkZGxld2FyZTEkMCIGA1UEAwwbc2hp Yi1wcHJkLm1pZGRsZXdhcmUudnQuZWR1MB4XDTE1MDMzMTE3NTQ1MVoXDTIwMDMz MDE3NTQ1MVowga4xCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJnaW5pYTETMBEG A1UEBwwKQmxhY2tzYnVyZzE8MDoGA1UECgwzVmlyZ2luaWEgUG9seXRlY2huaWMg SW5zdGl0dXRlIGFuZCBTdGF0ZSBVbml2ZXJzaXR5MRMwEQYDVQQLDApNaWRkbGV3 YXJlMSQwIgYDVQQDDBtzaGliLXBwcmQubWlkZGxld2FyZS52dC5lZHUwggEiMA0G CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC115mM3qIxxFAoGkwjGvpmQGqi3NhN st418It0iG4BVZR8UrruBsGBbH69G3ggDTKGRgJNA5HDcdZZMuWXqiNOQfWNTweA pezxK941Ax1+tV5h0vbsx0JOGtMVabGYFcty/DNb9yu5XOLEc8aGQAxSusuU5WOp 1XS0b7TXJBQfjPywXGcOpcVl2+GedDmjEeVKmxjfoW/HklLZjn1gCrxsJOzIwnOx arbbc08ki97c5/Tu0BEvPeqSecOjRX2zlA3YHnPKvfj5lMRoD77az4RC4H8rNdE/ IAqQVYt90OeTVShMad4uR/c42me45Rx+LQSFKL+dShXxIYXCYuF35y7bAgMBAAGj UDBOMB0GA1UdDgQWBBRHBJo36Os/RfOmR7yWQDsxgiQF4jAfBgNVHSMEGDAWgBRH BJo36Os/RfOmR7yWQDsxgiQF4jAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUA A4IBAQBToc/vEzySf7dFQjLqWJpmGxZgFo5xoVP66XF0qPIqAMKR1LLToetmLA0l NeuY5HzcpcuD5ILAHc7IZB+5RFSam1yQIj8L9u/KZTr+sdgyNm2KDHGhEmTTUB63 JsAPDsCX8Uri2bGOk1JTnaNf/zTQxD4xD5tc/dsOUubw27xLX46LuN4w6GSvbQ+D RGfMNHwWfa0PXRqOMktEB4KRMimTVu7FfRX/NI8Qt1cMl0Ur/EKapBVy58SChwsS ekCkx5H2+ar5TQpn8MoyloboaroHeHtFlQxhUY6fJWjcvZke6hY0W9MMubaovizq AzGwzzUtK3/d7PxUuTm7H1vsPcEs

https://shib-dev.middleware.vt.edu (VT dev)

MIIELzCCAxegAwIBAgIJAKme38tuxFhTMA0GCSqGSIb3DQEBBQUAMIGtMQswCQYD VQQGEwJVUzERMA8GA1UECAwIVmlyZ2luaWExEzARBgNVBAcMCkJsYWNrc2J1cmcx PDA6BgNVBAoMM1ZpcmdpbmlhIFBvbHl0ZWNobmljIEluc3RpdHV0ZSBhbmQgU3Rh dGUgVW5pdmVyc2l0eTETMBEGA1UECwwKTWlkZGxld2FyZTEjMCEGA1UEAwwac2hp Yi1kZXYubWlkZGxld2FyZS52dC5lZHUwHhcNMTUwMjExMTcwODA0WhcNNDIwNjI5 MTcwODA0WjCBrTELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlhMRMwEQYD VQQHDApCbGFja3NidXJnMTwwOgYDVQQKDDNWaXJnaW5pYSBQb2x5dGVjaG5pYyBJ bnN0aXR1dGUgYW5kIFN0YXRlIFVuaXZlcnNpdHkxEzARBgNVBAsMCk1pZGRsZXdh cmUxIzAhBgNVBAMMGnNoaWItZGV2Lm1pZGRsZXdhcmUudnQuZWR1MIIBIjANBgkq hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjFa4zod03mVQCDBzjEdFuvMWHTEblM7h CJnov+CVxFi1u0HJWIBpBE2kD3LqsxreNqSmR2Nb8BFih5KVjTEXiVZtcgYlvvHw PfnQjeVrrsYJhcLoBa9EPrJnVAX1Z5JmL/8fFzBexJ2EcLGPUcv4P7P12YJhRG83 vpujMC4oCcWRnmIFVRCFbtJIVTFo/ULL2NLdN8MEBorrov4479agCWPN+UYidC5g nSZ/lWzkViv2zH+833Eqs/PtrNnstWe+L8qntt+/RLEJZbHJxcIKhwwVdUd+8Ww4 xAGQm6jzJBTWyWduBPq4uSPvffyuAcabFfXkw69aD0te5hNLcGjuXwIDAQABo1Aw TjAdBgNVHQ4EFgQUv0N6hl+PtqbCYj/+8IqUOk146C4wHwYDVR0jBBgwFoAUv0N6 hl+PtqbCYj/+8IqUOk146C4wDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOC AQEAQXH6Fk4gkuVQ6hrk7QZL7kr72VgdY5j7MBgTHGqcNUUl/9enC2hbPOxBvon0 cCKb0eYplMKSOF/GcVAWZPEi0USQLty24pzhRBYCK9EXqSyX7WMj8I18J31cKu79 rxTaEARYgR4dPPxPZjatUGMSjPbER7qCQ4j2ISrUb3jCXv7L25HePvNoYi+Je5TW iyj2tyxEgOudCbz7DmI1R8QBS4kbK4y+eTx+Yk1bZtzoF8G7w0QqzTHA5S/KA9Ml PTnwsr5lKEEug5gT5xx0Yf4nHEdPZ9k6tymJJ53yItRH6VbfkgzW6/Q67x0aw8/U OQeMob6M11U/QVKBIxxYVXVDxw==

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 SHOULD 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 encrypting SAML messages sent to from the IdP to the SP. If the use attribute is present, it MUST declare the “encryption” value.
  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.

NOTE: While encryption is strictly optional, it is strongly recommended. If the SP does not declare an encryption certificate in metadata, encryption is disabled for that relying party.

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:

  1. urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (default, recommended)
  2. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  3. urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName

The details of these formats are discussed in the SAML Name Identifiers section.

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

Unique Identifiers

The following attribute are suitable for use as unique identifiers:

  1. eduPersonTargetedID
  2. uid
  3. uupid/authId
  4. virginiaTechID

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-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 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, pending consent, to all InCommon service providers that meet either of the following criteria:

  1. Identifies InCommon as the registrant
  2. Identifies as a member of the REFEDS R&S category

The latter category broadly extends the scope of services beyone InCommon to international services that peer with InCommon via EduGAIN. Note that R&S attributes are not released if the user rejects the consent request.

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.

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">bob@example.com</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 bob@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:

  1. urn:oasis:names:tc:SAML:2.0:nameid-format:persistent (default, recommended)
  2. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  3. urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName

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.

Persistent Format

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:

  1. Opaque
  2. 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:

  1. [uid]@vt.edu
  2. [virginiaTechID]@vt.edu
  3. [uupid]@vt.edu

The attribute used is a function of the release policy in effect for the relying party.

Windows Domain Format

Windows format is appropriate when the name identifier MUST be unqualified. The following attributes are available in order of precedence:

  1. [uid]
  2. [virginiaTechID]
  3. [uupid]

The attribute used is a function of the release policy in effect for the relying party.

Attribute Precedence

The attribute used for either of the above formats depends on attribute release policies in effect. The following table indicates the source attribute used for email and Windows format name identifiers as a function of policy.

NameID Source Attribute Release Policies
uid UID
uid UID, VTID
uid UID, VTID, EPPN
uid UID, VTID, EPPN, R&S
uid UID, VTID, R&S
virginiaTechID VTID
virginiaTechID VTID, EPPN
virginiaTechID VTID, R&S
uupid EPPN
uupid EPPN, 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 is authorized to receive the desired source attribute by requesting release policies per the table above.

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.