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
2. VT

It is not necessary to exchange metadata for integrations that occur via InCommon Federation, which is one of the primary benefits of federation. For custom integrations that use the VT metadata, it is typically necessary to manually exchange metadata. The IdP metadata for every tier is available for download to provide to service providers:

1. Metadata for login.vt.edu
2. Metadata for pprd.login.vt.edu
3. Metadata for dev.login.vt.edu

Entity IDs

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

Certificates

Our IdP uses different certificates depending on the integration context. Typically it is not necessary to obtain certificates or other integration coordinates for an integration through the InCommon Federation. For custom integrations that use the VT metadata source, we have a certificate for each IdP instance:

1. PEM-encoded cert for login.vt.edu
2. PEM-encoded cert for pprd.login.vt.edu
3. PEM-encoded cert for dev.login.vt.edu

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 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:

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:

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:

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.

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.

AWS integration

AWS account holders within the VT organization may enable SAML authentication against Login by following the steps outlined in the following sections. Note that only AWS Console access is supported at the time of writing; we hope to be able to support CLI and API access in the future.

Mark ED groups as AWS IAM roles

Define the ED groups you wish to be IAM roles in one or more AWS accounts for which you want SAML authentication and then use the ED REST API for groups to mark the group for an IAM role in a particular AWS account.

# Check whether the "sis" group is indicated as an AWS IAM role
curl -H"Authorization: Bearer $JWT" 'https://api.middleware.vt.edu/v1/groups/sis?with=replication'
 
{
    "creationDate": "2016-04-27T10:02:02-04:00",
    "displayName": null,
    "expirationDate": "2022-06-13T00:00:00-04:00",
    "uugid": "sis",
    "targets":
    [
        "google.com:a:vt.edu"
    ]
}
 
# Mark the "sis" group for use as an IAM role in AWS account 175568166460
curl -H"Authorization: Bearer $JWT" -XPOST -d"system=urn:amazon:webservices:175568166460" \
  'https://api.middleware.vt.edu/v1/groups/sis/targets'
 
# Confirm that AWS role is enabled on the "sis" group
curl -H"Authorization: Bearer $JWT" 'https://api.middleware.vt.edu/v1/groups/sis?with=replication'
 
{
    "creationDate": "2016-04-27T10:02:02-04:00",
    "displayName": null,
    "expirationDate": "2022-06-13T00:00:00-04:00",
    "uugid": "sis",
    "targets":
    [
        "google.com:a:vt.edu",
        "urn:amazon:webservices:175568166460"
    ]
}

# For sake of completeness, the following command may be used at a later date
# to remove a group from an IAM role in AWS account 175568166460
curl -H"Authorization: Bearer $JWT" -XDELETE \
  'https://api.middleware.vt.edu/v1/groups/sis/targets/urn:amazon:webservices:175568166460'

Please note that an ED group may be tagged for use in many AWS accounts. See the ED REST API docs for complete documentation and usage examples.

Make ED groups visible to Login

The shib ED service that performs LDAP group queries must be able to see groups in order to release them to AWS. Since groups are not visible to other services by default, so the shib service must be explicitly added to the VIEWER role on every group that is intended to be an AWS IAM role. Viewers may be managed with Group Manager or via the REST API as follows.

# Make the "sis" group viewable by the shib service
curl -XPOST -H"Authorization: Bearer $JWT" -d'kind=service&id=shib' \
  'https://api.middleware.vt.edu/groups/sis/viewers'

Create SAML provider

For each AWS account, go to the IAM section and create a SAML provider named Login (case sensitive). You will need the SAML metadata for Login in order to complete the process.

Test

Once the steps above have been completed, you may begin testing by authenticting to the AWS console using the following URL:

https://login.vt.edu/profile/SAML2/Unsolicited/SSO?providerId=urn:amazon:webservices