Sunday, October 31, 2004

Shibboleth

Components | Profiles | Attributes | Metadata | Summary ]

Shibboleth, a project of Internet2/MACE, is both a specification and an implementation of a federated identity management solution for higher education. For notational consistency, the current Shibboleth Architecture specification is written in the language of SAML2, which itself is based on Liberty 1.2.

The Shibboleth architecture extends the SAML1 single sign-on and attribute exchange mechanisms by specifying service-provider-first SSO profiles and enhanced features for user privacy. An optional WAYF ("Where are you from?") service provides a means for identity provider discovery.

As an implementation, Shibboleth is built on top of an open-source implementation of SAML 1.1 called OpenSAML. Shibboleth 1.2, the current version of the implementation, is available for download at

Shibboleth 1.2 supports the browser/POST profile only. Later implementations of Shibboleth will support the browser/artifact profile as well. Note that Shibboleth does not specify a single logout profile.

Shibboleth Components

The functional components of a conforming Shibboleth implementation include the following:

  • Identity Provider (formerly called an origin)
    • Authentication Authority

      The authentication authority issues authentication (authn) assertions to other components. The authentication authority is integrated with the IdP's authentication service (the details of which are out of scope).

    • Single Sign-On Service

      A single sign-on (SSO) service is the first point of contact at the IdP. The SSO service initiates the authentication process at the IdP and ultimately redirects the client to the inter-site transfer service (unless the function of the SSO service and inter-site transfer service are combined, which is encouraged). Note: The SSO service is not defined by SAML 1.1 but is defined by SAML 2.0.

    • Inter-Site Transfer Service

      The inter-site transfer service issues HTTP responses according to the browser/POST and browser/artifact profiles. The inter-site transfer service interacts with the authentication authority behind the scenes to produce the required authentication assertion. Note: The concept of inter-site transfer service has been deprecated in SAML 2.0.

    • Artifact Resolution Service

      If the browser/artifact profile is used, the IdP sends an artifact to the SP instead of the actual assertion. (An artifact is a reference to an authentication assertion.) The SP then sends the artifact to the artifact resolution service at the IdP via a back-channel exchange. In return, the IdP sends the required authentication assertion to the SP.

    • Attribute Authority

      The attribute authority processes <samlp:AttributeQuery> requests, that is, it issues attribute assertions. The attribute authority authenticates and authorizes any requests it receives (since such requests may come from either administrators or principals) before responding.

  • Service Provider (formerly called a target)
    • Assertion Consumer Service (formerly called a SHIRE)

      The assertion consumer service is the service provider endpoint of the SSO exchange. It processes the authentication assertion returned by the inter-site transfer service (or artifact resolution service, depending on the profile used), initiates an optional attribute query (see below), establishes a security context at the SP, and redirects the client to the desired target resource.

    • Attribute Requester (formerly called a SHAR)

      An attribute requester (at the SP) and the attribute authority (at the IdP) may conduct a back-channel attribute exchange once a security context has been established at the SP. That is, the SP and IdP interact directly, bypassing the principal.

  • WAYF Service

    An optional WAYF service is operated independently of the SP and IdP. The WAYF is used by the SP to determine the principal's preferred IdP, with or without user interaction. The WAYF is essentially a proxy for the authn request passed from the SP to the SSO service at the IdP. It must therefore fully support the authentication request protocol described below.

Note: Only the components whose name ends in "Service" have browser-facing URIs. The attribute authority is also a web service, but it is only accessible by authorized attribute requesters.

Shibboleth Profiles

Shibboleth specifies two browser-based SSO profiles and a service that may be used with either profile:

  1. Browser/POST Profile
  2. Browser/Artifact Profile
  3. WAYF Service

While the corresponding SAML 1.1 profiles begin with a request to the IdP, the Shibboleth profiles are service-provider-first, and therefore more complicated.

To accommodate SP-first profiles, Shibboleth introduces the notion of authentication request. A Shibboleth authn request is a URL-encoded message sent to an SSO service endpoint at the IdP. The following parameters are included in the query string:

  • providerId

    The providerId parameter is the unique id (usually a URI) of the SP. The IdP may use the providerId to perform special handling or processing of the authn request.

  • shire

    The shire parameter (so named for historical reasons) is the URI of the assertion consumer service endpoint at the SP. When using the browser/POST profile, this URI becomes the value of the FORM element's ACTION attribute. For the browser/artifact profile, the value of the shire parameter is the redirect URL used by the inter-site transfer service.

  • target

    The target parameter is the URI of the target resource. Regardless of the profile used, the target parameter must be preserved by the IdP.

  • time

    The (optional) time parameter is the current time in seconds past the epoch. It is used to avoid caching issues on the client. It is important that the time parameter not be used as any kind of security measure.

Here is an example of a Shibboleth authn request (without URL encoding for clarity):

https://idp.com/shibboleth/SSO?
providerId=https://sp.com/shibboleth/&
shire=https://sp.com/shibboleth/SSO&
target=https://sp.com/myresource&
time=1084819377

Detailed handling of this request is outlined in the subsections below.

Shibboleth Browser/POST Profile

Here is a possible implementation of the Shibboleth Browser/POST Profile. The message flow begins with a request for a secured resource at the SP.

  1. The client requests a target resource at the SP:
    https://sp.com/myresource
    The SP performs a security check on behalf of the target resource. If a valid security context at the SP already exists, skip steps 2–7.
  2. The SP redirects the client to the single sign-on (SSO) service at the IdP. Three parameters (providerId, shire, target) are appended to the redirect URL. (The optional time parameter is omitted in this example.)
  3. The client requests the SSO service at the IdP:
    https://idp.com/shibboleth/SSO?
    providerId=id&shire=acs&target=target
    where
    id = https://sp.com/shibboleth/
    acs = https://sp.com/shibboleth/SSO/POST
    target = https://sp.com/myresource
    The SSO service processes the authn request and performs a security check. If the user does not have a valid security context, the IdP identifies the principal (details omitted).
  4. The SSO service responds with an HTML form:
    ...
    <form method="post" 
          action="https://sp.com/shibboleth/SSO/POST" ...>
      <input type="hidden" name="TARGET" value="target">
      <input type="hidden" name="SAMLResponse" value="response">
      ...
      <input type="submit" value="Submit">
    </form>
    ...
    where the value of the TARGET parameter has been preserved from step 3. The value of the SAMLResponse parameter is the base64 encoding of a SAML Response element:
    <samlp:Response
      xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
      MajorVersion="1" MinorVersion="1"
      Recipient="https://sp.com/shibboleth/SSO/POST"
      ResponseID="..."
      IssueInstant="...">
      <ds:Signature 
        xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>...</ds:SignedInfo>
        <ds:SignatureValue>...</ds:SignatureValue>
        <ds:KeyInfo>...</ds:KeyInfo>
      </ds:Signature>
      <samlp:Status>
        <samlp:StatusCode Value="samlp:Success"/>
      </samlp:Status>
      <saml:Assertion
        xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
        MajorVersion="1" MinorVersion="1"
        AssertionID="..."
        Issuer="https://idp.com/shibboleth/"
        IssueInstant="...">
        <saml:Conditions 
          NotBefore="..." 
          NotOnOrAfter="...">
          <saml:AudienceRestrictionCondition>
            <saml:Audience>
              https://sp.com/shibboleth/
            </saml:Audience>
          </saml:AudienceRestrictionCondition>
        </saml:Conditions>
        <saml:AuthenticationStatement
          AuthenticationInstant="..."
          AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
          <saml:Subject>
            <saml:NameIdentifier 
              NameQualifier="https://idp.com/shibboleth/"
              Format="urn:mace:shibboleth:1.0:nameIdentifier">
              3f7b3dcf-1674-4ecd-92c8-1544f346baf8
            </saml:NameIdentifier>
            <saml:SubjectConfirmation>
              <saml:ConfirmationMethod>
                urn:oasis:names:tc:SAML:1.0:cm:bearer
              </saml:ConfirmationMethod>
            </saml:SubjectConfirmation>
          </saml:Subject>
        </saml:AuthenticationStatement>
      </saml:Assertion>
    </samlp:Response>
    Note that the SAML Response must be digitally signed by the identity provider.
  5. The client issues a POST request to the assertion consumer service at the service provider. To automate the submission of the form, the following line of JavaScript may appear anywhere on the page:
    window.onload = 
      function() { document.forms[0].submit(); };
    This assumes of course that the page contains a single FORM element. If JavaScript is disabled on the client, the user simply presses the submit button.
  6. The assertion consumer service processes the authn response, creates a security context at the SP and redirects the client to the target resource.
  7. The client requests the target resource at the SP (again):
    https://sp.com/myresource
  8. Since a security context exists, the SP returns the resource to the client.
Shibboleth Browser/Artifact Profile

Here is a possible implementation of the Shibboleth Browser/Artifact Profile. The message flow begins with a request for a secured resource at the SP.

  1. The client requests a target resource at the SP:
    https://sp.com/myresource
    The SP performs a security check on behalf of the target resource. If a valid security context at the SP already exists, skip steps 2–9.
  2. The SP redirects the client to the single sign-on (SSO) service at the IdP. Three parameters (providerId, shire, target) are appended to the redirect URL. (The optional time parameter is omitted in this example.)
  3. The client requests the SSO service at the IdP:
    https://idp.com/shibboleth/SSO?
    providerId=id&shire=acs&target=target
    where
    id = https://sp.com/shibboleth/
    acs = https://sp.com/shibboleth/SSO/Artifact
    target = https://sp.com/myresource
    The SSO service processes the authn request and performs a security check. If the user does not have a valid security context, the IdP identifies the principal (details omitted).
  4. The SSO service redirects the client to the assertion consumer service at the SP. A TARGET parameter and a SAMLart parameter are appended to the redirect URL.
  5. The client requests the assertion consumer service at the SP:
    https://sp.com/shibboleth/SSO/Artifact?
    TARGET=target&SAMLart=artifact
    where the value of the TARGET parameter is preserved from step 3 and the SAMLart parameter is a SAML artifact.
  6. The assertion consumer service dereferences the artifact by sending a SAML Request to the artifact resolution service at the IdP:
    <samlp:Request 
      xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" 
      MajorVersion="1" MinorVersion="1" 
      RequestID="..." 
      IssueInstant="...">
      <samlp:AssertionArtifact>
        artifact
      </samlp:AssertionArtifact>
    </samlp:Request>
    where artifact is the SAML artifact at step 5.
  7. The artifact resolution service at the IdP returns a SAML Response (containing an authn assertion) to the assertion consumer service at the SP:
    <samlp:Response
      xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
      MajorVersion="1" MinorVersion="1"
      Recipient="https://sp.com/shibboleth/SSO/Artifact"
      ResponseID="..."
      InResponseTo="..."
      IssueInstant="...">
      <samlp:Status>
        <samlp:StatusCode Value="samlp:Success"/>
      </samlp:Status>
      <saml:Assertion
        xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
        MajorVersion="1" MinorVersion="1"
        AssertionID="..."
        Issuer="https://idp.com/shibboleth/"
        IssueInstant="...">
        <saml:Conditions 
          NotBefore="..."
          NotOnOrAfter="..."/>
        <saml:AuthenticationStatement
          AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"
          AuthenticationInstant="...">
          <saml:Subject>
            <saml:NameIdentifier 
              NameQualifier="https://idp.com/shibboleth/"
              Format="urn:mace:shibboleth:1.0:nameIdentifier">
              3f7b3dcf-1674-4ecd-92c8-1544f346baf8
            </saml:NameIdentifier>
            <saml:SubjectConfirmation>
              <saml:ConfirmationMethod>
                urn:oasis:names:tc:SAML:1.0:cm:artifact
              </saml:ConfirmationMethod>
            </saml:SubjectConfirmation>
          </saml:Subject>
        </saml:AuthenticationStatement>
      </saml:Assertion>
    </samlp:Response>
  8. The assertion consumer service processes the authn response, creates a security context at the SP and redirects the client to the target resource.
  9. The client requests the target resource at the SP (again):
    https://sp.com/myresource
  10. Since a security context exists, the SP returns the resource to the client.
WAYF Service

A WAYF ("Where are you from?") service is an intermediary between the SP and the IdP. In general, the SP does not know the user's preferred IdP. The process whereby the SP determines the appropriate IdP is called identity provider discovery (generally, a very difficult problem).

Shibboleth specifies an (optional) WAYF service to aid the SP in IdP discovery. In practice, the SP sends its authn request to the WAYF, which somehow determines the user's preferred IdP (through unspecified means) and then subsequently redirects the client to the desired IdP. The WAYF preserves the values of all parameters except the time parameter, which is updated.

A real world example is the WAYF service operated by InQueue. As an experiment, click the link below:

This resource is protected by a Shibboleth SP, which redirects you to the InQueue WAYF. In your browser's location field, you will see the following redirect URL:
https://wayf.internet2.edu/InQueue/WAYF?
target=https%3A%2F%2Fwayf.internet2.edu%2FInQueue%2Fsample.jsp&
shire=https%3A%2F%2Fwayf.internet2.edu%2FShibboleth.shire&
time=1099609640&
providerId=urn%3Amace%3Ainqueue%3Aexample.edu

Now view the source of the InQueue WAYF form and note the hidden fields that preserve the parameters of the original authn request.

Attributes

Compared to other federated identity management solutions, Shibboleth has a well-defined attribute sharing and management process. Shibboleth specifies the use of a standard SOAP-based attribute query protocol from SAML 1.1, a standardized directory schema called eduPerson, and attribute release policies that allow both users and administrators to control the flow of attributes from IdP to SP. As a result, Shibboleth provides powerful authorization capabilities while protecting the privacy of users.

Attribute Query Protocol

Although attributes may be embedded in the authn assertion transferred from IdP to SP, Shibboleth specifies an optional back-channel exchange using SAML over SOAP over HTTP. The SP sends a <samlp:AttributeQuery> element to the IdP and receives an <saml:AttributeStatement> in return. For example, the SP may send an attribute query something like the following:

<samlp:Request
  xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
  IssueInstant="2004-05-25T22:46:10Z" 
  MajorVersion="1" MinorVersion="1"
  RequestID="aaf2319617732113474afe114412ab72">
  <samlp:AttributeQuery 
    Resource="https://sp.com/shibboleth/">
    <saml:Subject 
      xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
      <saml:NameIdentifier 
        Format="urn:mace:shibboleth:1.0:nameIdentifier"
        NameQualifier="https://idp.com/shibboleth/">
        082dd87d-f380-4fd6-8726-694ef2bb71e9
      </saml:NameIdentifier>
    </saml:Subject>
  </samlp:AttributeQuery>
</samlp:Request>

The IdP may respond with the following attribute assertion:

<samlp:Response
  xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
  InResponseTo="aaf2319617732113474afe114412ab72"
  IssueInstant="2004-05-25T22:46:10.940Z" 
  MajorVersion="1" MinorVersion="1"
  ResponseID="b07b804c7c29ea1673004f3d6f7928ac">
  <samlp:Status>
    <samlp:StatusCode Value="samlp:Success"/>
  </samlp:Status>
  <saml:Assertion 
    xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
    AssertionID="a144e8f3adad594a9649924517abe933"
    IssueInstant="2004-05-25T22:46:10.939Z" 
    MajorVersion="1" MinorVersion="1"
    Issuer="https://idp.com/shibboleth/">
    <saml:Conditions 
      NotBefore="2004-05-25T22:46:10.939Z"
      NotOnOrAfter="2004-05-25T23:16:10.939Z">
    </saml:Conditions>
    <saml:AttributeStatement>
      <saml:Subject>
        <saml:NameIdentifier 
          Format="urn:mace:shibboleth:1.0:nameIdentifier"
          NameQualifier="https://idp.com/shibboleth/">
          082dd87d-f380-4fd6-8726-694ef2bb71e9
        </saml:NameIdentifier>
      </saml:Subject>
      <saml:Attribute 
        AttributeName="urn:mace:dir:attribute-def:eduPersonEntitlement"
        AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
        <saml:AttributeValue>
          urn:mace:oclc.org:100277910
        </saml:AttributeValue>
        <saml:AttributeValue>
          urn:mace:example.edu:exampleEntitlement
        </saml:AttributeValue>
        <saml:AttributeValue>
          urn:mace:incommon:entitlement:common:1
        </saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

It is important that the attribute authority be protected against unauthorized access.

Directory Schema

In a cross-domain federated environment, a standard approach to user attributes is crucial. It is essential that providers be on the same page with respect to attributes. If not, this will be a major impediment to federated identity on a large scale.

To address this issue, Internet2 has developed an LDAP object class for higher education called eduPerson, which is administered by EDUCAUSE:

eduPerson is derived from the standard LDAP object class called inetOrgPerson (RFC 2798), which itself is based on other standard LDAP classes (see, e.g., RFC 2256).

Of all the attributes defined by this hierarchy of object classes, approximately 40 attributes have been defined by InCommon as common identity attributes:

Common Attributes  
Highly recommended   6
Suggested 10
Optional 25
  41

For example, here are InCommon's six "highly recommended" attributes:

Attribute Name Example
givenName Mary
sn (surname) Smith
cn (common name) Mary Smith
eduPersonScopedAffiliation   student@some.idp.edu
eduPersonPrincipalName mary.smith@some.idp.edu
eduPersonTargetedID 6xCI1qyLfj12h9wiogTmcebZcL0
 

The NameIdentifier used in the previous examples is a privacy-preserving, opaque identifier that precludes the need to positively identify the principal. Unlike NameIdentifier, which is a transient identifier, eduPersonTargetedID is a persistent identifier. See the EduPerson Specification (200312) for more information about eduPersonTargetedID.

Attribute Release Policy

An attribute release policy (ARP) dictates what user attributes are released to individual service providers. For example, consider the following XML representation of an ARP:

<?xml version="1.0" encoding="UTF-8" ?> 
<arp:AttributeReleasePolicy 
  xmlns:arp="urn:mace:shibboleth:arp:1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:mace:shibboleth:arp:1.0 shib-arp-1.0.xsd">
  <arp:Description>
    This policy applies to all SPs.
  </arp:Description>
  <arp:Rule>
    <arp:Target><arp:AnyTarget /></arp:Target>
    <arp:Attribute 
      name="urn:mace:eduPerson:1.0:eduPersonPrincipalName">
      <arp:AnyValue release="permit" />
    </arp:Attribute>
    <arp:Attribute 
      name="urn:mace:eduPerson:1.0:eduPersonAffiliation">
      <arp:Value release="permit">member@some.idp.edu</arp:Value>
    </arp:Attribute>
  </arp:Rule>
</arp:AttributeReleasePolicy>

The <arp:Target> element lists the SPs to which the rule applies. The above ARP applies to all SPs but individual SPs may be listed. Regular expressions may be used to denote groups of SPs. See the ARP specification for additional examples.

Once the applicable SPs have been defined, the ARP lists the attributes that may be released to those SPs. In the above example, attribute eduPersonPrincipalName may be released to any SP. Attribute eduPersonAffiliation may also be released, but only one value is permitted, namely, "member@some.idp.edu".

Metadata

Both IdPs and SPs publish information about themselves in special XML files called metadata files. Since metadata precisely identify the provider and the services it offers, metadata files are digitally signed for security and privacy.

Shibboleth specifies a minimal subset of the SAML2 metadata specification. Only four md:RoleDescriptorType elements are defined by Shibboleth:

  1. <md:IDPSSODescriptor>
  2. <md:SPSSODescriptor>
  3. <md:AuthnAuthorityDescriptor>
  4. <md:AttributeAuthorityDescriptor>

These metadata elements correspond to the SSO service (IdP), the assertion consumer service (SP), the authentication authority (IdP), and the attribute authority (IdP), respectively.

For example, here is an example of a Shibboleth IdP metadata file (with signatures and keys omitted):

<md:EntityDescriptor 
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
  entityID="https://idp.edu/shibboleth/">
  <ds:Signature>...</ds:Signature>
  <md:IDPSSODescriptor
    protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.0:protocol:v1.1
urn:mace:shibboleth:1.0">
<md:KeyDescriptor use="signing"> <ds:KeyInfo> <ds:KeyName>IdP SSO Key</ds:KeyName> </ds:KeyInfo> </md:KeyDescriptor> <md:ArtifactResolutionService isDefault="true" index="0" Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01" Location="https://idp.edu/shibboleth/ArtifactResolution"/> <md:NameIDFormat> urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName </md:NameIDFormat> <md:NameIDFormat> urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress </md:NameIDFormat> <md:NameIDFormat> urn:mace:shibboleth:1.0:nameIdentifier </md:NameIDFormat> <md:SingleSignOnService Binding="urn:mace:shibboleth:1.0:profiles:authnRequest" Location="https://idp.edu/shibboleth/SSO"/> </md:IDPSSODescriptor> <md:AttributeAuthorityDescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.0:protocol:v1.1"> <md:KeyDescriptor use="signing"> <ds:KeyInfo> <ds:KeyName>IdP AA Key</ds:KeyName> </ds:KeyInfo> </md:KeyDescriptor> <md:AttributeService Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding" Location="https://idp.edu/shibboleth/AA/SOAP"/> <saml:Attribute AttributeName="urn:mace:eduPerson:1.0:eduPersonPrincipalName" AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri"/> <saml:Attribute AttributeName="urn:mace:eduPerson:1.0:eduPersonAffiliation" AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri"> <saml:AttributeValue>member</saml:AttributeValue> <saml:AttributeValue>student</saml:AttributeValue> <saml:AttributeValue>faculty</saml:AttributeValue> <saml:AttributeValue>employee</saml:AttributeValue> <saml:AttributeValue>staff</saml:AttributeValue> </saml:Attribute> <md:NameIDFormat> urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName </md:NameIDFormat> <md:NameIDFormat> urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress </md:NameIDFormat> <md:NameIDFormat> urn:mace:shibboleth:1.0:nameIdentifier </md:NameIDFormat> </md:AttributeAuthorityDescriptor> <md:Organization> <md:OrganizationName xml:lang="en"> Identity Provider University </md:OrganizationName> <md:OrganizationDisplayName xml:lang="en"> Identity Provider University @ Some Location </md:OrganizationDisplayName> <md:OrganizationURL xml:lang="en"> http://www.idp.edu/ </md:OrganizationURL> </md:Organization> </md:EntityDescriptor>

Likewise, here is an example of a Shibboleth SP metadata file:

<md:EntityDescriptor 
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
  entityID="https://sp.edu/shibboleth/">
  <ds:Signature>...</ds:Signature>
  <md:SPSSODescriptor
    protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.0:protocol:v1.1">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:KeyName>SP SSO Key</ds:KeyName>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>
      urn:mace:shibboleth:1.0:nameIdentifier
    </md:NameIDFormat>
    <md:AssertionConsumerService isDefault="true" index="0"
      Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"
      Location="https://sp.edu/shibboleth/SSO/POST"/>
    <md:AssertionConsumerService index="1"
      Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"
      Location="https://sp.edu/shibboleth/SSO/Artifact"/>
    <md:AttributeConsumingService index="0">
      <md:ServiceName xml:lang="en">
        Service Provider University Portal
      </md:ServiceName>
      <md:RequestedAttribute
        AttributeName="urn:mace:eduPerson:1.0:eduPersonEntitlement"
        AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
        <saml:AttributeValue>
          https://sp.edu/entitlements/123456789
        </saml:AttributeValue>
      </md:RequestedAttribute>
    </md:AttributeConsumingService>
  </md:SPSSODescriptor>
  <md:Organization>
    <md:OrganizationName xml:lang="en">
      Service Provider University
    </md:OrganizationName>
    <md:OrganizationDisplayName xml:lang="en">
      Service Provider University @ Some Location
    </md:OrganizationDisplayName>
    <md:OrganizationURL xml:lang="en">
      http://www.sp.edu/
    </md:OrganizationURL>
  </md:Organization>
</md:EntityDescriptor>

Summary

Shibboleth enjoys a number of advantages over other federated identity management solutions:

  • relatively simple architecture (compared to Liberty 1.2 and SAML 2.0, e.g.)
  • an open-source implementation
  • good online technical support
  • emphasis on user privacy (ARPs, e.g.)
  • standardized attributes (via eduPerson)
  • well-developed federations (InQueue, InCommon)

Of course Shibboleth has some disadvantages as well:

  • difficult to install
  • not fully compliant with SAML 1.1
  • limited exposure outside academia
  • no single logout profile

For an excellent, high-level introduction to Shibboleth and related Internet2 technology, see:

Tuesday, October 12, 2004

SAML1

Security Assertion Markup Language (SAML) is an XML standard for exchanging authentication and authorization data between security domains, that is, between an identity provider and a service provider. SAML is a product of the OASIS Security Services Technical Committee:

The single most important problem that SAML is trying to solve is the web single sign-on (SSO) problem. SSO solutions at the intranet level abound (using cookies, e.g.) but extending these solutions beyond the intranet has been problematic and has led to the proliferation of proprietary technologies that do not interoperate. SAML has become the definitive standard underlying many web SSO solutions in the identity management problem space.

SAML assumes the principal (often a user) has enrolled with at least one identity provider. This identity provider is expected to provide local authentication services to the principal. However, SAML does not specify the implementation of these local services; indeed, SAML does not care how local authentication services are implemented (although individual service providers most certainly will).

SAML 1.0

SAML 1.0 was adopted as an OASIS standard in Nov 2002. SAML has undergone one minor and one major revision since V1.0, which itself is a relatively simple protocol. SAML 1.0 is of more than historical interest, however, since the Federal E-Authentication Initiative has adopted SAML 1.0 as its core technology.

Fortunately, versions 1.0 and 1.1 of SAML are similar. See the document

  • Differences between OASIS Security Assertion Markup Language (SAML) V1.1 and V1.0 [SAMLDiff]

for specific differences between the two standards. This article concentrates on SAML 1.1 since it is the definitive standard on which most other standards and implementations depend.

SAML 1.1

Assertions | Protocol | Bindings | Profiles ]

SAML 1.1 was ratified as an OASIS standard in Sep 2003. The critical aspects of SAML 1.1 are covered in detail in the following three documents:

  • Conformance Program Specification for the OASIS Security Assertion Markup Language (SAML) [SAMLConform]
  • Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) [SAMLCore]
  • Bindings and Profiles for the OASIS Security Assertion Markup Language (SAML) [SAMLBind]

If you are new to SAML, your first reading should probably be the following document:

  • Technical Overview of the OASIS Security Assertion Markup Language (SAML) [SAMLOverview]

There are at least two open source implementations of SAML 1.1:

  1. OpenSAML <http://www.opensaml.org/>
  2. SourceID SAML 1.1 Toolkit <http://www.sourceid.org/download.do>

OpenSAML is associated with Shibboleth while the SourceID tookit has its roots in Project Liberty. Both are based on the same standard and should therefore interoperate.

SAML 1.1 Assertions

SAML assertions are usually transferred from identity providers to service providers. Assertions contain statements that service providers use to make access control decisions. Three types of statements are provided by SAML:

  1. Authentication statements
  2. Attribute statements
  3. Authorization decision statements

Authentication statements assert to the service provider that the principal did indeed authenticate with the identity provider at a particular time using a particular method of authentication. Other information about the principal may be disclosed in an authentication statement. For example, in the authentication statement below, the e-mail address of the principal is disclosed to the service provider:

<saml:Assertion
  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
  MajorVersion="1" MinorVersion="1"
  AssertionID="..."
  Issuer="https://idp.org/saml/"
  IssueInstant="2002-06-19T17:05:37.795Z">
  <saml:Conditions 
    NotBefore="2002-06-19T17:00:37.795Z"
    NotOnOrAfter="2002-06-19T17:10:37.795Z"/>
  <saml:AuthenticationStatement
    AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"
    AuthenticationInstant="2002-06-19T17:05:17.706Z">
    <saml:Subject>
      <saml:NameIdentifier
        Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
        user@mail.idp.org
      </saml:NameIdentifier>
      <saml:SubjectConfirmation>
        <saml:ConfirmationMethod>
          urn:oasis:names:tc:SAML:1.0:cm:artifact
        </saml:ConfirmationMethod>
      </saml:SubjectConfirmation>
    </saml:Subject>
  </saml:AuthenticationStatement>
</saml:Assertion>

An e-mail address (as in the above example) will suffice in a large number of situations. In some cases, however, additional information is needed before a service provider can make an access control decision. As an example, suppose that students are allowed to access scholarships data. An attribute statement can indicate whether or not the principal has an affiliation of "student", which the service provider uses to allow or deny access (resp.) to the scholarships application:

<saml:assertion 
  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
  MajorVersion="1" MinorVersion="1"
  Issuer="https://idp.edu/saml/" ...>
  <saml:Conditions NotBefore="..." NotAfter="..."/>
  <saml:AuthenticationStatement
    AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:X509-PKI"
    AuthenticationInstant="...">
    <saml:Subject>...</saml:Subject>
  </saml:AuthenticationStatement>
  <saml:AttributeStatement>
    <saml:Subject>...</saml:Subject>
    <saml:Attribute 
      AttributeName="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"
      AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
      <saml:AttributeValue Scope="idp.edu">
        member
      </saml:AttributeValue>
      <saml:AttributeValue Scope="idp.edu">
        student
      </saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>

Attributes are often obtained from an LDAP directory, so consistent representations of attributes across security domains is crucial. We will revisit this question in the thread on Federations.

In the above example showing how a student might obtain access to a scholarships application, the service provider is functioning as both a policy enforcement point and a policy decision point. In some situations, it may be preferrable to associate the policy decision point with the identity provider. In this case, the service provider passes a URI to the identity provider who asserts an authorization decision statement that dictates whether or not the principal should be allowed access to the secured resource at the given URI.

<saml:assertion 
  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
  MajorVersion="1" MinorVersion="1"
  Issuer="https://idp.org/saml/" ...>
  <saml:Conditions .../>
  <saml:AuthorizationDecisionStatement
    Decision="Permit"
    Resource="https://sp.org/confidential_report.html">
    <saml:Action>read</saml:Action>
    <saml:Subject>...</saml:Subject>
  </saml:AuthorizationDecisionStatement>
</saml:Assertion>

The three statement types are not mutually exclusive. For example, both authentication statements and attribute statements may be included in a single assertion (as shown above). This precludes the need to make subsequent round trips between the service provider and identity provider.

SAML 1.1 Protocol

The SAML protocol is a simple request-response protocol. A SAML requester sends a SAML Request element to a responder:

<samlp:Request 
  xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" 
  MajorVersion="1" MinorVersion="1" 
  RequestID="..." 
  IssueInstant="...">
  <!-- insert other SAML elements here -->
</samlp:Request>

Similarly, a SAML responder returns a SAML Response element to the requester:

<samlp:Response
  xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
  MajorVersion="1" MinorVersion="1"
  ResponseID="..."
  InResponseTo="..."
  IssueInstant="...">
  <!-- insert other SAML elements here, including assertions -->
</samlp:Response>

The bindings and profiles needed to affect this message exchange are detailed in the following sections.

SAML 1.1 Bindings

SAML 1.1 defines just one binding, the SAML SOAP binding. A compatible SAML 1.1 implementation must implement SAML over SOAP over HTTP (a synchronous protocol). Other transport mechanisms are permitted provided the protocol-independent aspects of the SAML SOAP binding are observed (see section 3.1.2 of [SAMLBind]).

The SAML 1.1 SOAP binding is built on top of SOAP 1.1 (the numbering is purely coincidental). A SAML requester wraps a SAML Request element within the body of a SOAP message. Similarly, a SAML responder returns a SAML Response element within the body of a returned SOAP message. If there is an error, the responder returns a SOAP fault code instead.

Any SAML markup must be included in the SOAP body. SAML 1.1 does not define any SAML-specific SOAP headers. A requester is free to insert any SOAP headers it wishes (although none are required).

Recall that in SOAP 1.1, a SOAPAction HTTP header must be included with each HTTP request (although its value may be empty). A SAML requester may give the following value to the SOAPAction header:

SOAPAction: http://www.oasis-open.org/committees/security

A SAML responder must not depend on this value, however.

A secure connection is not required for SAML requests and responses, but in those situations where message integrity and confidentiality are required, HTTP over SSL 3.0 or TLS 1.0 with a server-side certificate is required.

A SAML responder may return a "403 Forbidden" response when it refuses to respond to a SAML requester. A responder must return a "500 Internal Server Error" response in the event of a SOAP error (a SOAP fault element must be included as well). Otherwise, a "200 OK" response is returned, even in the presence of a SAML processing error. Such a response will include a SAML Status element in the SOAP body.

SAML 1.1 Profiles

Browser/Artifact Profile | Browser/POST Profile ]

In general, profiles describe the HTTP exchanges required to ultimately transfer assertions from an identity provider to a service provider. SAML 1.1 specifies two browser-based, single sign-on profiles:

  1. Browser/Artifact Profile
  2. Browser/POST Profile

These profiles support cross-domain single sign-on (SSO). The specification does not define any additional profiles. In particular, SAML 1.1 does not support a profile to secure a web service message nor does it support a single logout profile.

Both SAML 1.1 profiles begin at the inter-site transfer service, which is managed by the identity provider. How the principal arrives at the transfer service in the first place is not dictated by the specification. See sections 4.1 and 4.2 of [SAMLOverview] for possible scenarios. In practice, a client accessing a secured resource at a service provider will be redirected to the inter-site transfer service at the identity provider. Note, however, that the precise sequence of steps needed to accomplish this is not outlined by SAML 1.1. (See section 4.3 of [SAMLOverview] for some rough ideas along these lines.) This issue is thoroughly addressed in SAML 2.0.

After visiting the inter-site transfer service, the principal is transferred to the assertion consumer service at the service provider. Exactly how the principal is transferred from the inter-site transfer service to the assertion consumer service depends on the profile used. In the case of the Browser/Artifact Profile, a redirect is used; in the case of the Browser/POST Profile, the client issues a POST request (with or without user intervention).

To expedite processing by the assertion consumer service, two separate URLs are specified:

  1. Artifact Receiver URL (Browser/Artifact Profile)
  2. Assertion Consumer URL (Browser/POST Profile)

These and other URLs may be recorded in a SAML metadata archive.

Note that a conforming SAML 1.1 identity provider must provide an inter-site transfer service. Similarly, a SAML 1.1 service provider must provide an assertion consumer service.

SAML 1.1 Browser/Artifact Profile

The Browser/Artifact Profile employs a "pull" mechanism. The profile essentially passes an SSO assertion from the identity provider to the service provider by reference, which is subsequently dereferenced via a back-channel exchange (i.e., the service provider "pulls" the assertion from the identity provider).

The SAML 1.1 Browser/Artifact Profile specifies the following six (6) steps (the terminology used in the original document has been modified slightly to conform to the emerging SAML 2.0 specification):

  1. Request the Inter-site Transfer Service

    The principal (user) requests the inter-site transfer service at the identity provider:

    https://idp.org/saml/TransferService?TARGET=target

    where target is the location of the desired resource at the service provider, say, https://www.sp.org/home. In other words, the following GET request is issued by the client:

    GET /saml/TransferService?TARGET=target HTTP/1.1
    Host: idp.org

    The profile does not specify how the URL to the transfer service (with target parameter) is obtained by the client.

  2. Redirect to the Assertion Consumer Service

    The principal is redirected to the assertion consumer service at the service provider; that is, the following response is returned to the client:

    HTTP/1.1 302 Found
    Location: https://sp.org/saml/ACS/Artifact?TARGET=target&SAMLart=artifact

    where artifact is a reference to an assertion the identity provider is willing to provide upon request. Important: It is assumed that the principal has already established a security context at the identity provider, otherwise the identity provider would not be able to subsequently assert the authenticity of the principal.

  3. Request the Assertion Consumer Service

    The client requests the assertion consumer service at the service provider:

    https://sp.org/saml/ACS/Artifact?TARGET=target&SAMLart=artifact

    where target and artifact are as before. In other words, the following GET request is issued by the client:

    GET /saml/ACS/Artifact?TARGET=target&SAMLart=artifact HTTP/1.1
    Host: sp.org
  4. Request the Artifact Resolution Service

    The assertion consumer service at the service provider begins a back-channel exchange with the artifact resolution service at the identity provider. The following SAML SOAP message is bound to an HTTP POST request:

    POST /saml/ArtifactResolutionService HTTP/1.1
    Host: idp.org
    Content-Type: text/xml
    Content-Length: nnn
    SOAPAction: http://www.oasis-open.org/committees/security
    
    <?xml version="1.0"?>
    <SOAP-ENV:Envelope
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
      <SOAP-ENV:Header/>
      <SOAP-ENV:Body>
        <samlp:Request 
          xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" 
          MajorVersion="1" MinorVersion="1" 
          RequestID="_192.168.16.51.1024506224022" 
          IssueInstant="2002-06-19T17:03:44.022Z">
          <samlp:AssertionArtifact>
            artifact
          </samlp:AssertionArtifact>
        </samlp:Request>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

    where artifact was previously sent from the identity provider to the service provider in steps 2 and 3.

  5. Respond with a SAML Assertion

    The artifact resolution service at the identity provider completes the back-channel exchange by responding with a SAML assertion:

    HTTP/1.1 200 OK
    Content-Type: text/xml
    Content-Length: nnnn
    
    <?xml version="1.0"?>
    <SOAP-ENV:Envelope
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
      <SOAP-ENV:Header/>
      <SOAP-ENV:Body>
        <samlp:Response
          xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
          MajorVersion="1" MinorVersion="1"
          ResponseID="_P1YaA+Q/wSM/t/8E3R8rNhcpPTM="
          InResponseTo="_192.168.16.51.1024506224022"
          IssueInstant="2002-06-19T17:05:37.795Z">
          <samlp:Status>
            <samlp:StatusCode Value="samlp:Success"/>
          </samlp:Status>
          <!-- insert Assertion element here -->
        </samlp:Response>
      </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

    where the Assertion element was discussed earlier.

  6. Respond to the Principal's Original Request

    The assertion consumer service inspects the SAML Response element returned by the artifact resolution service, creates a security context at the service provider and redirects the client to the target resource.

SAML 1.1 Browser/POST Profile

The Browser/POST Profile relies on a "push" operation. In contrast to the Browser/Artifact Profile, the Browser/POST Profile passes an SSO assertion by value. No back-channel communication is needed in this case. In effect, the identity provider "pushes" the assertion to the service provider.

The SAML 1.1 Browser/POST Profile specifies the following four (4) steps (the terminology used in the original document has been modified slightly to conform to the emerging SAML 2.0 specification):

  1. Request the Inter-Site Transfer Service

    The principal (user) requests the inter-site transfer service at the identity provider:

    https://idp.org/saml/TransferService?TARGET=target

    where target is the desired resource at the service provider, say, https://www.sp.org/home. In other words, the following GET request is issued by the client:

    GET /saml/TransferService?TARGET=target HTTP/1.1
    Host: idp.org

    The profile does not specify how the URL to the transfer service (with target parameter) is obtained by the client.

  2. Respond with an HTML Form

    The inter-site transfer service returns an HTML document containing a FORM element whose ACTION attribute is the URL of the assertion consumer service:

    HTTP/1.1 200 OK
    Content-Type: text/html
    Content-Length: nnnn
    
    ...
    <form method="post" 
          action="https://sp.org/saml/ACS/post" ...>
      <input type="hidden" name="TARGET" value="target">
      <input type="hidden" name="SAMLResponse" value="response">
      ...
      <input type="submit" value="Submit">
    </form>
    ...

    where the value of the TARGET parameter has been preserved from step 1. The value of the SAMLResponse parameter is the base64 encoding of a SAML Response element, more-or-less the same SAML Response element returned by the identity provider in step 5 of the Browser/Artifact Profile. In the case of the Browser/Artifact Profile, however, the SAML Response must be digitally signed by the identity provider.

    Important: It is assumed that the principal has already established a security context at the identity provider, otherwise the inter-site transfer service would not be able to provide an authentication statement in the SAML Response element.

  3. Request the Assertion Consumer Service

    The client requests the assertion consumer service at the service provider:

    POST /saml/ACS/post HTTP/1.1
    Host: sp.org
    Content-Type: application/x-www-form-urlencoded
    Content-Length: nnnn
    
    TARGET=target&SAMLResponse=response

    To automate the submission of the form, the following line of JavaScript may appear anywhere on the page:

    window.onload = function () { document.forms[0].submit(); }

    This assumes of course that the page contains a single FORM element.

  4. Respond to the Principal's Original Request

    The assertion consumer service inspects the SAML Response element, creates a security context on the service provider and redirects the client to the target resource.

Friday, October 08, 2004

SOAP

SOAP is an XML technology for sending and receiving messages across the Internet. More often than not, SAML assertions are bound to SOAP messages, so a basic understanding of SOAP is essential for federated identity management.

SOAP is not necessarily bound to HTTP, but HTTP is the only substrate we consider here. In other words, for the purposes of this discussion, SOAP runs on top of HTTP, and SAML is wrapped inside of SOAP. We often use the phrase "SAML over SOAP over HTTP" when discussing these related technologies.

Originally, SOAP was an acronym for "Simple Object Access Protocol", but this turned out to be a misnomer since SOAP has nothing to do with "object access" in the object-oriented programming sense of the phrase. So today we no longer think of "SOAP" as an acronym although the capitalization persists.

SOAP 1.1 is based on a note sent to the W3C (from Microsoft, IBM and others) in May 2002. This note did not become a formal W3C recommendation but SOAP 1.1 remains a de facto SOAP standard nonetheless. For example, all versions of SAML rely on SOAP 1.1.

Subsequently, the W3C began work on SOAP 1.2, which culminated in a comprehensive set of recommendations published in June 2003. See the W3C page XML Protocol Working Group for links to these documents and other SOAP-related activity. The document SOAP Version 1.2 Part 0: Primer is particularly useful for a basic understanding of SOAP messaging.

A SOAP message consists of a so-called SOAP envelope inside an HTTP wrapper. Like HTTP, a soap envelope consists of two parts, a header and a body. Of these, only the SOAP body is required. As we will see, all parts of a SOAP message are XML-encoded (although SOAP 1.2 permits MIME attachments to SOAP messages, much like SMTP).

A SOAP 1.1 message inside an HTTP POST request might look like this:

POST /trscavo/servlet/HttpEchoServlet HTTP/1.1
Host: voyager.cs.bgsu.edu:8080
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction:

<?xml version="1.0">
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header>...</SOAP-ENV:Header>
  <SOAP-ENV:Body>...</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Note that in SOAP 1.1, messages are bound to POST requests only. Also, since the SOAPAction header has been removed in SOAP 1.2, we will not discuss it further.

A similar SOAP 1.1 message wrapped inside an HTTP response would be:

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0">
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header>...</SOAP-ENV:Header>
  <SOAP-ENV:Body>...</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Some changes to the SOAP message structure were made in version 1.2. First of all, SOAP 1.2 messages may be bound to either GET or POST requests. An example of the latter is the following:

POST /trscavo/servlet/HttpEchoServlet HTTP/1.1
Host: voyager.cs.bgsu.edu:8080
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0">
<env:Envelope 
  xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Header>...</env:Header>
  <env:Body>...</env:Body>
</env:Envelope>

Observe the differences between SOAP 1.1 and 1.2 (when bound to HTTP POST requests):

  • The SOAPAction header has been removed, which is generally true in SOAP 1.2.
  • A new content type called application/soap+xml has been declared, a content type specifically defined for use with SOAP 1.2.
  • An XML declaration has been added to the request body.
  • The SOAP namespace URI has changed.

A SOAP 1.2 message bound to an HTTP response is formulated much like before:

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

<?xml version="1.0">
<env:Envelope 
  xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Header>...</env:Header>
  <env:Body>...</env:Body>
</env:Envelope>

The primary differences are the content type and namespace URI as mentioned above.

A popular open source SOAP processor is called Axis from the Apache project. The current production release of Axis (v1.1) fully supports SOAP 1.1 and partially implements SOAP 1.2. Version 1.2 of Axis, which is at "release candidate" stage at the time of this writing, is said to be fully compatible with SOAP 1.2.

SOAP can be used for synchronous or asynchronous messaging. Synchronous messaging, where the sender blocks until a reply is received, is simplest. Fortunately, SAML SOAP bindings are synchronous, which we consider in detail in the next thread.

Federated Identity Management

Identity Management includes the process and infrastructure associated with the creation, maintenance, and use of digital identities. The Burton Group defines Federated Identity Management as the

Use of agreements, standards, and technologies to make identity and entitlements portable across loosely coupled, autonomous identity domains. <http://www.cio.gov/eauthentication/documents/BurtonGroupEAreport.pdf>

Informally, Federated Identity Management is authentication, authorization, and single sign-on at the inter-enterprise level, that is, at the level of the extranet. The mantra of federated identity management solutions is:

Authenticate locally, authorize globally.

In a typical federated scenario, a principal (user) is enrolled with a small number of identity providers. Any number of service providers may authorize access to their respective web resources on the basis of SAML assertions obtained from the principal's identity provider(s). These assertions never contain credentials and need not even reveal the identity of the principal; that is, privacy is a primary concern of federated systems.

SAML, Shibboleth, and Liberty Alliance are important technologies within the identity management (IdM) problem space:

Most, if not all federated IdM solutions are based on Security Assertion Markup Language (SAML). For example, the current versions of Shibboleth and Liberty are based on SAML 1.1. Note that SAML is more than a markup language. It consists of protocols, bindings and profiles, in addition to the standard XML markup used for assertions.

Diverse IdM standards are converging upon SAML 2.0, recently released for public comment by OASIS. SAML 2.0 builds on previous work, especially Liberty. Future versions of Shibboleth and Liberty will no doubt be compatible with SAML 2.0.

An important related development within the federal government is the E-Authentication Initiative, which focuses on SAML 1.0:

Of particular interest is the E-Authentication Interoperability Lab, which certifies the compatibility of vendor systems.

It is apparent that the technology is converging (SAML 2.0) and quickly becoming a commodity. The next important step is the development of federations, sometimes called circles of trust. There are a number of production quality federations under development around the world, including:

The enterprise question whether or not to federate is a difficult one involving significant legal, administrative, and political issues.

Subsequent threads will explore the various versions of SAML, Shibboleth and Liberty, and summarize the issues surrounding cross-enterprise federation.

Friday, July 30, 2004

Building Blocks Conference Notes

Blackboard Developers Conference
Georgetown University, 2004

Monday, July 26

09:00–09:45 a.m.
Keynote Session
Matthew Pittinsky

Highlights:
  • We are in the midst of a transition from e-learning applications in individual courses to a campus-wide network learning environment involving all members of the institution
  • Blackboard is now a public company
  • One third of this year's conference attendees attended last year's conference as well
  • The Blackboard Developers Network (BbDN) has grown from 115 (2003) to 245 (2004)
  • 6141 Building Blocks SDK downloads
  • 7276 Building Blocks (B2) downloads
  • Of the 104 Building Blocks in the catalogue, 74 are for the Academic Suite, and 50% are free
  • .NET SDK released Feb 2004
  • Commitment to standards continues (IMS e-Portfolio, SIF integration)
Top 10 Building Blocks:
  1. 10. User Performance Module (USF)
  2. 9. SCORM 1.2 Compliant Player 1.0
  3. 8. Discussion Grader (JJC)
  4. 7. Dictionary and Thesaurus
  5. 6. User Participation Portal Module (USF)
  6. 5. My Journal (Baylor U)
  7. 4. Blackboard Link Checker
  8. 3. Who's Online Portal Module (Seneca)
  9. 2. Bb Content Player (IMS, SCORM, etc.)
  10. 1. Advanced Group Management (FSU)
Sneak Peaks:
  • Application Pack strategy continues
  • App Pack 2 due in about a month
    • Content System SDK
    • built-in SCORM support
    • internationalization
    • ChalkBox
      • "chalktitles" offered by Houghton Mifflin, Pearson Education, Thomson Learning
      • synchronize rosters, SSO, post to gradebook
    • Continued development of Content System
      • v1.2 Q3 2004
      • v2.0 Q4 2004
    • Academic Suite 7.0 due Q1 2005
2003–2004 Priorities:
  1. Increase access to BbDN
    • Free accounts to Academic Suite clients (enterprise)
    • "Not quite free" accounts to Commerce Suite clients
  2. Comply with evolving standards (SAKAI membership sought)
  3. Improve developer support
    • Provide comprehensive test data
    • Provide B2 training courses (such as B2 Essentials)
  4. Grow market receptivity (e.g., "Blackboard Enabled" program)
  5. Hire Building Blocks Architect/Evangelist

09:45–10:30 a.m.
What is .NET?
Bruce Jackson

Take-Home Lesson:
.NET is a web application framework modeled after J2EE
Important Fact Learned:
CLR runs on Windows only
Important Fact Learned:
Passport is going away!
Notes:
  • Common Language Runtime (CLR) manages .NET "managed code"
  • Primary advantage of .NET is code agnosticism
  • Source code compiles to "intermediate language" (IL)
  • CLR manages memory automatically (like Java)
  • IL code is portable across architectures (32b, 64b, etc.)
  • .NET is not yet UI independent- .NET addresses security issues (big changes coming!)
  • Objects passed by value (not reference), which assumes copius bandwidth
  • Service Oriented Architecture (SOA) is emphasized
  • WS-Security, a form of "federated trust", is supported
  • WS-Security and Liberty Alliance may be merging!
  • [Even Liberty Alliance and Shibboleth are talking!]
  • Kerberos remains a major player

10:45–11:30 a.m.
Data Storage and Migration (Java)
Bob Alcorn

Take-Home Lesson:
Data storage possibilities are somewhat limited
Important Fact Learned:
Can not write into the Blackboard database!
Notes:
  • Goals: Portability and structured data
  • Types of data:
    1. private data (config data, e.g.)
    2. content data
    3. tool data (discussion tool, e.g.)
    4. extended attributes
  • Private data stored in properties files in local directories (see blackboard.platform.plugin.PlugInConfig)
  • Extended data provided via "registries" (see blackboard.data.registry)
  • Content organized by course
  • Use @X@object.attribute@X@ template variables (which have a corresponding API)
  • Tool storage:
    • Properties files (the lowest common denominator)
    • XML documents
    • 3rd party storage (e.g., Berkeley DB, Lucene)
  • Migration from R5 to R6 is one-time operation
  • Course Copy is a handy tool

11:30–12:15 p.m.
My First Building Block (.NET)
Biran Zhang

Take-Home Lesson:
.NET/C# is very similar to J2EE
Important Fact Learned:
Visual Studio is required for .NET development
Notes:
  • A Building Block (B2) is a web application
  • See package blackboard.security.authorization for access control
  • Possible uses of B2:
    • bridge to external system
    • publish a web service
    • content type
    • tools
      • student tool
      • course tool
      • system tool
      • communication tool
    • portal module
  • MS .NET framework requires Visual Studio .NET
  • File structure is similar to J2EE (/WEB-INF directory, e.g.)
  • MS Virtual PC development environment permits standardization

01:30–02:15 p.m.
.NET APIs in Detail
Biran Zhang

Notes:
  • Blackboard .NET namespace is very similar to Java API
  • See blackboard.data.announcement, e.g.
  • Strongly typed enumerations are useful

02:15–03:00 p.m.
Java APIs in Detail
Bob Alcorn

Take-Home Lesson:
A comprehensive Buidling Block will touch numerous APIs
Important Fact Learned:
Use new reflection-based persistence methods instead of standard persisters and loaders
Notes:
  • General in-depth introduction to B2 Java APIs
  • Base object: blackboard.data.BbObject
  • Data objects
    • Content: blackboard.data.content
    • Course: blackboard.data.course
    • Gradebook: blackboard.data.gradebook
  • Persistence objects
  • Use new reflection-based persistence methods (e.g., persist)
  • The persistance manager is proprietary
  • Service lookups via BbServiceManager
  • Other services:
    • Context: blackboard.platform.context
    • Session: blackboard.platform.session
    • File System: blackboard.platform.filesystem
    • Log: blackboard.platform.log
    • Security: blackboard.platform.security
  • Note: Not all clients honor cookies, so sometimes session data is encoded in the URL (URL rewriting)
  • Don't use BbList and BbEnum in package blackboard.base (since J2SE 1.5 is coming)
  • blackboard.base.FormattedText provides "smart" text handling
  • blackboard.base.GenericComparator for sorting
  • Portal: blackboard.portal.external
  • Tag libraries facilitate UI standardization and integration
  • XML manifest file enables deployment

03:30–04:15 p.m.
Blackboard and Content Types
Tracy Engwirda

Notes:
  • Updated JSPs can be dropped into place without restarting the server
  • Enable the /webapps/manager context in development environment
  • Custom style sheets can not be applied (in a standard way) to custom content
  • External data is stored in properties files

05:00–08:00 p.m.
International Spy Museum

Appetizers, libations, and a delicious catered dinner were provided at the International Spy Museum in downtown Washington, D.C. After dinner, we toured the museum, which was very entertaining! (The highlight exhibit was a working replica of James Bond's Austin-Martin getaway car.) An hour and a half was barely enough time to scratch the surface.

Tuesday, July 27

09:00–09:45 a.m.
Java Event API
Tracy Engwirda

Take-Home Lesson:
The event API is a real-time alternative to the snapshot mechanism
Important Fact Learned:
Event API data model based on IMS specification
Important Fact Learned:
The "event" API is geared towards data integration, not "events" in the usual sense of the word
Notes:
  • In Bb6, the event API is exposed by package blackboard.admin.*
  • Read:
    • Advanced Integration and Data Management Manual
    • Administrative API Specifications
  • The event API data model mirrors the snapshot mechanism
  • The data model is based on the IMS 1.01 Enterprise Specification)
  • In terms of data model, the event API is an extension of the B2 API (entities and persisters)
  • Classes are stored in cms-admin.jar (add this JAR file to your classpath)
  • Using the event APIs:
    • command-line application
      • on Bb app server
      • on other server via snapshot client
    • Building Blocks application (but use care)
    • Web Service
    • RPC wrappers
  • Event handlers are constructed with database triggers (outside of the LS)
  • Event listener classes will be added in future APIs

09:45–10:30 a.m.
Blackboard 6 Authentication
Tom Scavo

Take-Home Lesson:
A custom authentication module should extend BaseAuthenticationModule
Important Fact Learned:
A lightweight web service can provide validation services to arbitrary web applications
Notes:
  • Blackboard 6 Standard Authentication
    • Authentication Types
    • Authentication API (HttpAuthModule)
    • BaseAuthenticationModule
    • Authentication Framework
  • Blackboard 6 Custom Authentication
    • LogAuthenticationModule
    • AbstractAuthModule
    • GenericAuthModule
    • Installation
  • BGSU Authentication
    • BGAuth and BGAuthValidator
    • BGAuthModule
  • Developer's Workshop

10:45–11:30 a.m.
Building Blocks and Web Services (Java)
Bob Alcorn

12:45–01:30 p.m.
Security and Authentication with Building Blocks (Java)
Tom Joyce

Take-Home Lesson:
Blackboard security built on Java security model
Important Fact Learned:
Custom authentication is not possible in .NET because Bb security is built on the Java security model
Notes:
  • General security concepts
    • Authentication
    • Authorization
    • Privacy
    • Integrity
  • Declaring permissions in the manifest file is often a trial-and-error process
  • Blackboard security is based on the Java security model:
    • Java Secure Sockets Extension (JSSE)
    • Java Cryptography Extensions (JCE)
    • Java Generic Security Services (GSS) API
    • CertPath API
    • Java Authentication and Authorization Service (JAAS)
    • Code Security Model
  • Authentication services are available to Building Blocks via AccessManagerService
  • Authorization services are also available to Building Blocks (see PlugInUtil)
  • Two types of roles: system (e.g., admin) and course (e.g., TA)
  • Security information available via java.lang.Class

02:00–02:45 p.m.
Building Blocks and Blackboard—A Look Ahead
Bob Alcorn, Dan Cane, David Yaskin

Notes:
  • Internal event queues are coming (forced by the introduction of the Content System, which must coordinate with the Learning System)
  • e-Portfolios provided by the Content System
  • Selective release of content is coming
  • Transaction System Account Management
  • JJC's Discussion Board Grader would be useful to faculty

Wednesday, July 07, 2004

Web Security

Basic security principles include:

  • Availability
  • Integrity
  • Authentication
  • Confidentiality
  • Non-repudiation

Secure Sockets Layer (SSL), a web encryption technology originally developed by Netscape, provides basic web security. All HTTP traffic over SSL (https) is encrypted (in both directions). Beneficial consequences include:

  • Confidentiality: The contents of messages are unreadable by 3rd-party observers
  • Integrity: The contents of messages can not be altered or tampered with in transit
  • Authentication: The sender and receiver are assured of each other's identity

Most browsers ship with SSL certificates installed. On the server, SSL modules (e.g., openSSL) and certificates (from Verisign, e.g.) must be installed. A crypto card can alleviate server bottlenecks.

The SSL network layer lies between IP and HTTP on the protocol stack. Versions include SSL v2.0 and SSL v3.0. Transport Layer Security (TLS) is an extension of SSL proposed by the Internet Engineering Task Force (IETF). TLS v1.0 is roughly equivalent to SSL v3.0. When an SSL connection is established, a client and server negotiate the best combination of cryptographic techniques.

To avoid security issues, the following are recommended:

  • Store only hashed passwords in the database
  • Submit the login page over SSL, otherwise the password is passed in the clear and may be sniffed
  • Make passwords difficult to guess and install intruder alarms that detect random or systematic guessing of passwords
  • Avoid sensitive data in URLs (i.e., GET requests) since URLs are logged
  • To avoid GET requests (the result of redirects), return an HTML form with an onload handler that automatically POSTs the hidden fields in the form

A session ID (like a password) must be protected. To prevent session hijacking, a session-based application must run over SSL. If the session mechanism uses cookies:

  • Set the secure attribute on the cookie, otherwise it will be passed over insecure (non-SSL) connections
  • Avoid setting a timeout on the cookie, even a short timeout, since browsers might then write the cookie to disk

Set session timeouts (on the server) as short as possible. Like passwords, make the session ID difficult to guess and install intruder alarms that detect random or systematic guessing of session IDs.

Do not use IP addresses in an attempt to prevent session hijacking (since it doesn't work and only raises support issues). Remember: Logging out is a user's single best defense against session hijacking.

Access Control

The roles table discussed earlier provides Role-Based Access Control, a typical approach. It would be better, however, if the application were precluded from making access control decisions. Other types of access control are possible (a complex topic). Another approach involves groups and resources, which we discuss now.

For Group-Based Access Control, define groups and resources as follows:

  • groups( group, description )
  • resources( resource, url, link_text )

The url field is the URL of the protected resource. The link_text field is suitable for constructing hyperlinks (on a portal page, for instance).

The groups table has two columns:

CREATE TABLE groups (
  group       VARCHAR(12)  NOT NULL,
  description VARCHAR(60)  NOT NULL,
  PRIMARY KEY (group) );

The resources table has three columns:

CREATE TABLE resources (
  resource   VARCHAR(16)  NOT NULL,
  url        VARCHAR(80)  NOT NULL,
  link_text  VARCHAR(40)  NOT NULL,
  PRIMARY KEY (resource) );

The group and username fields are the primary keys of the groups and users tables, respectively.

A number of intersect tables are defined:

  • group_membership( group, username )
  • group_access( group, resource )
  • user_access( username, resource )

The group_membership table assigns users to groups. It has two columns:

CREATE TABLE group_membership (
  group      VARCHAR(12)  NOT NULL,
  username   VARCHAR( 8)  NOT NULL,
  PRIMARY KEY (group,username) );

The group_access table attaches groups to resources. It has two columns:

CREATE TABLE group_access (
  group      VARCHAR(12)  NOT NULL,
  resource   VARCHAR(16)  NOT NULL,
  PRIMARY KEY (group,resource) );

The group and resource fields are the the primary keys of the groups and resources tables, respectively.

The user_access table attaches individual users to resources. Like the group_access table, the user_access table has two columns:

CREATE TABLE user_access (
  username   VARCHAR( 8)  NOT NULL,
  resource   VARCHAR(16)  NOT NULL,
  PRIMARY KEY (username,resource) );

Individual user access is primarily for convenience.

What groups does a particular user belong to?

SELECT group FROM group_membership
  WHERE username = 'username';

What groups have access to a particular resource?

SELECT group FROM group_access
  WHERE resource = 'resource';

What users have direct access to a particular resource?

SELECT username FROM user_access
  WHERE resource = 'resource';

Now assume the web service knows the name of the protected resource that requests it. The web service does the following:

  1. Validates the session ID
  2. Authorizes the corresponding user

The latter depends on whether the user belongs to a privileged group.

What users have group access to a particular resource?

SELECT username FROM group_membership
  WHERE group IN (
    SELECT group FROM group_access
      WHERE resource = 'resource'
  );

Rewriting the subselect as a join:

SELECT username FROM group_membership, group_access
  WHERE group_membership.group = group_access.group
  AND resource = 'resource';

List all users having access to a particular resource:

SELECT username FROM user_access
  WHERE resource = 'resource'
UNION
SELECT username FROM group_membership
  WHERE group IN (
    SELECT group FROM group_access
      WHERE resource = 'resource'
  );

Recall that the default login target is a portal home page. Any authenticated user is allowed access to the portal page. The web service returns a list of URLs to the portal page, which it uses to construct a personalized home page.

What resources does a particular user have direct access to?

SELECT resource FROM user_access
  WHERE username = 'username';

What resources does a particular user have group access to?

SELECT resource FROM group_access
  WHERE group IN (
    SELECT group FROM group_membership
      WHERE username = 'username'
  );

Rewriting the subselect as a join:

SELECT resource FROM group_access, group_membership
  WHERE group_access.group = group_membership.group
  AND username = 'username';

What are the URLs of all the resources a particular user has access to?

SELECT url, link_text FROM resources
  WHERE resource IN (
    SELECT resource FROM user_access
      WHERE username = 'username'
    UNION
    SELECT resource FROM group_access
      WHERE group IN (
        SELECT group FROM group_membership
          WHERE username = 'username'
      )
  );

The URLs and the corresponding text are sufficient to construct a list of links.

Tuesday, July 06, 2004

Authentication Web Service Components

Assume the database components and web components for authentication/SSO are already in place. The next step is to integrate an application into the authentication/SSO framework.

Any given application must validate the session ID stored in the client-side cookie. Validation occurs at the time a protected resource is requested. Rather than install elaborate validation components in the application itself, we describe a validation web service that accepts validation requests via HTTP. To make use of the web service, an application need only do two things: 1) make an HTTP request, and 2) parse an XML document. These modest requirements make it relatively easy to integrate an application into the authentication/SSO framework.

The web service and the authentication controller share the same database (but are otherwise separate). When the web service receives a validation request, it checks to see if the given session ID is in the database. Validation succeeds if and only if the session ID is in the database. Subsequently an XML document is returned to the client application. The XML document encodes the validation response.

The web service relies on an XML template. This template is used to formulate a validation response. The XML DTD may be of ad hoc design or standard design (e.g., SAML).

The web service supports one action: validate. The corresponding URL is:

/auth/service?action=validate&SID=sid

A request for the validate action always results in an XML document. Both parameters (action and SID) are required. For enhanced security, a request for the validate action should be a POST request with SID parameter encoded in the body of the request.

When requested, a protected resource performs the following steps:

  1. Extract the cookie (SID) from the request
  2. If the cookie does not exist, redirect the client to the login page with parameter target=self
  3. If the cookie does exist, request the web service with SID as parameter
  4. If the parsed XML indicates failure, redirect the client to the login page
  5. If the parsed XML indicates success and the user possesses the desired role, return the requested resource to the client

When requested, the web service performs the following operations. If the session ID is in the sessions table, the request is valid:

SELECT username FROM sessions
  WHERE SID = 'sid';

Since the SID is the primary key of the sessions table, this query will return 0 or 1 results. If the request is valid, the web service determines the corresponding roles:

SELECT role FROM roles
  WHERE username = 'username';

The resulting roles are encoded in the XML and returned in the response along with the username.

It is up to the client application whether to enforce access restrictions. If the desired role is contained in the list of roles returned from the web service, access is allowed. Other approaches to access control (discussed later) remove this decision-making process from the application.

Authentication Web Components

Once the database components have been installed, the web components may be implemented. The web components needed for authentication include a login page and a controller. The login page has four form elements:

  1. a text field (username)
  2. a password field (password)
  3. a hidden field (target)
  4. a submit button (Login)

When the Login button is pressed, the form is submitted to the controller.

The controller processes all login and logout requests. After processing, the controller issues an HTTP 302 redirect or forwards the request to another component (e.g., the login page). The controller does not return HTML (or other markup).

The controller supports two actions: login and logout. The corresponding URLs are:

/auth/controller[?action=login[&target=target]]
/auth/controller?action=logout[&target=target]

The default action is the login action. A GET request for the login action results in the login page. A POST request for the login action includes two additional parameters: username and password. A POST request for the login action always results in a redirect.

A POST request for the login action causes the following steps to occur (in order):

  1. authenticate the user
  2. update the sessions table
  3. create the cookie
  4. redirect the client

Each step depends on the success of the previous step.

To authenticate the user, the controller hashes the password and queries the users table:

SELECT username FROM users
  WHERE username = 'username'
  AND password = 'hashedPswd';

The username and hashedPswd are the input username and the MD5 hash of the input password (resp.). The login action proceeds to the next step if the SELECT returns a result.

Next the controller creates and stores an unique session ID:

INSERT INTO sessions VALUES
  ( 'sid', 'username' );

These two steps constitute a database transaction, which must be executed atomically. A better approach is to write a database stored procedure:

stored_proc( 'username', 'hashedPswd' ) ==> 'sid'

The stored procedure authenticates and creates a session in one step.

If the login action succeeds, a cookie is created on the client:

Set-Cookie: SID=sid; path=/; domain=.my.com; secure

This creates a secure cookie visible throughout the my.com domain. The cookie persists for the life of the browser (max).

If authentication is unsuccessful, the controller redirects to the login page. If the authentication is successful and the request has a parameter called target, the controller redirects the client to the target URL. If there is no target parameter, the user is redirected to a personalized portal page.

A request for the logout action always results in a redirect. A GET logout request is equivalent to a POST logout request. In either case, the session ID is invalidated in the sessions table:

DELETE FROM sessions WHERE sid = 'sid';

Instead of physically deleting the session, it may be marked for deletion in the sessions table (with associated cleanup issues).

To complete the logout action, the cookie is expired on the client:

Set-Cookie: SID=; path=/; domain=.my.com; secure; 
  expires=Thursday, 01-Jan-70 00:00:00 GMT

This is a relatively minor issue however, since the corresponding entry in the sessions table has been invalidated. Any subsequent validation attempt will fail.

The target parameter allows seemless integration of the authentication framework. The value of the (optional) target parameter is an absolute URL. The controller redirects to the target URL after completing the action. The default login target is a portal page. The default logout target is the login page.

Monday, July 05, 2004

Authentication Database Components

Three database tables are required to implement a minimal authentication/single sign-on solution:

  1. users( username, password )
  2. sessions( sid, username )
  3. roles( username, role )

Alternatively, an LDAP directory may be used in lieu of a relational database.

The users table has two columns:

CREATE TABLE users (
  username  VARCHAR(8)  NOT NULL,
  password  CHAR(32)    NOT NULL,
  PRIMARY KEY (username) );

For security reasons, the password is stored as an MD5 hash (or other suitable hash value). In particular, cleartext passwords are not stored in the database. Instead, passwords are one-way hashed using MD5:

INSERT INTO users VALUES
  ( 'trscavo', MD5( 'nopass' ) ), ...

Regardless of input, an MD5 hash value is precisely 32 characters:

SELECT MD5( 'nopass' );
==> 0945fc9611f55fd0e183fb8b044f1afe

The sessions table has two columns:

CREATE TABLE sessions (
  sid       CHAR(13)    NOT NULL,
  username  VARCHAR(8)  NOT NULL,
  PRIMARY KEY (sid) );

The session ID (sid) is a unique sequence of 13 characters (or other suitable ID).

The roles table has two columns:

CREATE TABLE roles (
  username  VARCHAR(8)  NOT NULL,
  role      VARCHAR(20) NOT NULL,
  PRIMARY KEY (username,role) );

Access to protected resources is based on roles, which are assigned by the system administrator:

INSERT INTO roles VALUES
  ( 'trscavo', 'user' ),
  ( 'trscavo', 'administrator' );

Any given user may be assigned multiple roles.