Saml:SamlOverview

Authenticating web service calls with SAML

PAWN was designed to operate across multiple administrative domains. For example, in our archive testbed, we already have NARA, UMIACS, SDSC, and and handful of other partners. Each partners is accepting data from various outside groups. In this environment, it is not feasible to enforce any type of centralized authentication service. This presents a problem when a NARA partner wants to use a resource at UMIACS. Assuming that UMIACS doesn't have the ability to directly authenticate against NARA, how does a partner that can authenticate against NARA use UMIACS resources. In our case, the answer is to use SAML assertions.

A SAML assertion is just an XML file that contains information about who issued it, some statements about some (name, access priveleges, etc), and information to entire entegrity of the token and trust of the client. To access a remote resource in our example, an assertion is issued by NARA to the partner upon successful authentication at NARA (kinda kerb ticket like). The partner can then show that assertion along with proof that it's allowed to use that assertion to the UMIACS resource, and UMIACS will allow access. Of course there are layers of signatures, and key exchanges that go on under the hood to enable this and keep everything secure.

We use the WS-Security standard to enable initial authentication by username / password, and to handle SAML authenticated methods. In addition, we have some libraries to allow the generation and checking of SAML tokens. We've chosen to use the SAML 1.1 specification, and the OpenSAML toolkit.

This just covers how we use SAML tokens in the ADAPT project. There is a lot more to the specification than what we use. This includes token request services, and different types of token workflows. This is described at OASIS Security Services (SAML) TC page.

SAML Assertion

So, what is needed to allow SAML tokens, and what do these tokens contain?

A SAML assertion is nothing more than a bunch of statements about the holder of the assertion. In our case, we use an assertion that contains a single statement of type Attribute Statement. This statement includes who a client is, and what [[Saml:SamlRoles][role]] they are to perform in ADAPT.

A SAML assertion contains several parts, first is the assertion envolope that contains all statements and information about lifecycle and assertion integrity.

Assertion Container

Since the assertion is just a container for statements, the only piece of information we really care about is lifetime for an assertion and integrity information. Lifetime is done with a global Conditions statment that contains a start and end date for the validity of this certificate. The container also contains the issuer of the assrtion.

<Assertion AssertionID="dd140ccf344d51fa877b3714dd7f26c8" IssueInstant="2006-02-07T22:44:32.444Z" Issuer="http://umiacs.umd.edu" MajorVersion="1" MinorVersion="1">
   <Conditions NotBefore="2006-02-07T22:44:32.444Z" NotOnOrAfter="2006-02-07T22:44:32.444Z"/>

The integrity of an assertion can be checked by looking at the <nop>SignatureValue and <nop>KeyInfo sections. These contain the digital signature of the assertion and the certificate used to verify that signature. In PAWN, this would be the public key at a producer site, or scheduler. You can use this key to validate the integrity of certificate during transport, if you use the embedded key, you must check the signing path of that cert back to some trusted certificate authority. You will also need to check that the key is one that you expect (ie, not a different one signed by the same CA). In PAWN, we use a simplier system, each service that consumes these assertions will have a local copy of the Authorities certificate that they can validate the certificate against.

Services that will trust a site's assertions will need to get it's keys ahead of time. In an archive environment this exchange is feasable since the trust is largely between a central archive and remote sites, not necessarity between each remote site and every other site. There are project such as the Liberty Alliance and Shibboleth that address some of these issues.

<ds:SignatureValue>CvL4...</ds:SignatureValue>

    <ds:KeyInfo>
      <ds:X509Data>
        <ds:X509Certificate>MIIC...</ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>

Subject

The subject contains a <nop>NameIdentifier that gives us two pieces of information. First is has a <nop>NameQualifier, this is the domain or realm that this use belongs to. Second, it contains the identity of the user. We just use a plain text username here, but it's possible to embed any other information, ldap DN, xml, etc.

In <nop>PAWN, the nameQualifier is used to specify the domain of an individual user. In combination with the issuer, the namequalifier and actual value specify a unique entity.

<NameIdentifier NameQualifier="era">rlopez</NameIdentifier>

Second a subject contains confirmation information. In our case, this the assertion uses holder-of-key as a method for clients to prove they are the rightful owner of this certificate. There are additional confirmation methods, some of which are listed on Sun's xws tutorial Below the confirmation method, is a certificate that will be used for this. Holder-of-key says that a client must prove they are allowed to use this certificate by showing they have a private key corresponding to the certificate. In the case of web services, the private key proof is to sign the entire SOAP message with the private key, then verify that signature against the embedded cert.

Here is a what the subject confirmation part of a subject looks like:

<SubjectConfirmation>
  <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:holder-of-key</ConfirmationMethod>
  <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:X509Data>
      <ds:X509Certificate>MIID...</ds:X509Certificate>
    </ds:X509Data>
  </ds:KeyInfo>
</SubjectConfirmation>

Since the entire SAML token is by the issuer, and this signature can be verified, we can ensure that nobody changed the embedded certificate or other information and can trust what it says.

Attributes

We use attribute statements in ADAPT to send a list of all privileges a user has for a given package. a privilege in PAWN is divided into two parts, first is the type of privilege, and second is the action on that type. For example. 'Package Item' may be the type and 'Modify' may be the allowed action. The type is represented by the AttributeName and the action is represented by a list of AttributeValues. There are two special types that do not follow this pattern.

• package_id - contains the manager id number of the package as it's AttributeValue.
• package_structure - contains a record set document as its value.

Since the roles have to cross sites they need to have a common namespace. We've started outlining some available roles [[Main.SamlRoles][here]]. Of course a 3rd party is allowed to ignore roles that it doesn't seem fit. For example, the scheduler may only allow certain issuers to modify resource configuration.

Standard type and action

<Attribute AttributeName="schedule" AttributeNamespace="http://umiacs.umd.edu/adapt/saml">
   <AttributeValue>view</AttributeValue>
   <AttributeValue>create</AttributeValue>
   <AttributeValue>modify</AttributeValue>
   <AttributeValue>delete</AttributeValue>
</Attribute>

Special package_id attribute

<Attribute AttributeName="package_id" AttributeNamespace="http://umiacs.umd.edu/adapt/saml">
<AttributeValue>1</AttributeValue>
</Attribute>

Entire Assertion

The complete assertion that is used for authentication looks as follows:

<Assertion xmlns="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
           xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" AssertionID="fd653abed9ae5bcb59ab3665a149ab9f" 
           IssueInstant="2005-07-15T16:57:42.047Z" Issuer="http://umiacs.umd.edu" MajorVersion="1" MinorVersion="1">

  <Conditions NotBefore="2005-07-15T16:57:42.044Z" NotOnOrAfter="2005-07-15T16:57:42.044Z"></Conditions>

  <AttributeStatement>

    <Subject>
      <NameIdentifier NameQualifier="nara">rlopez</NameIdentifier>
      <SubjectConfirmation>
        <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:holder-of-key</ConfirmationMethod>
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
          <ds:X509Data>
            <ds:X509Certificate>MIID...</ds:X509Certificate>
          </ds:X509Data>
        </ds:KeyInfo>
      </SubjectConfirmation>
    </Subject>

    <Attribute AttributeName="role" AttributeNamespace="http://umiacs.umd.edu/adapt/saml">
      <AttributeValue>urn:pawn:role:user</AttributeValue>
    </Attribute>

  </AttributeStatement>

  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

    <ds:SignedInfo>
      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
      <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
      <ds:Reference URI="#fd653abed9ae5bcb59ab3665a149ab9f">

        <ds:Transforms>
          <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform>
          <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
            <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" 
                PrefixList="code ds kind rw saml samlp typens #default"></ec:InclusiveNamespaces>
          </ds:Transform>
        </ds:Transforms>

        <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
        <ds:DigestValue>vl8p6+i7ITSqRqqluuNwPTevwC0=</ds:DigestValue>
      </ds:Reference>
    </ds:SignedInfo>

    <ds:SignatureValue>CvL4...</ds:SignatureValue>

    <ds:KeyInfo>
      <ds:X509Data>
        <ds:X509Certificate>MIIC...</ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>

  </ds:Signature>
</Assertion>

Workflow

The workflow for using SAML authentication in PAWN follows:

1. Any service that will trust a 3rd party Authority will need a copy of it's certificate
2. Each site will need to have certificates of any certificate authority used.
3. A client connects to an Authority and authenticated with local security information (username/password) and supplies a certificate that it will use to prove it's identity.
4. The Authority authenticates the client and verifies the supplied certificate against CA certificate.
5. Authority create assertion with client roles, identity, supplied cert, signed the assertion and returns to client.
6. (optional) If a client doesn't trust the transport to the Authority, it can validate the assertion.
7. A client connects to a 3rd party web service. The SOAP message contains the SAML assertion in the header plus a signature of the soap message. Signature is created with private key corresponding to embedded cert.
8. The consuming service verifies the message signature was generated with the embedded cert, it also checks the saml signature against the Authorities certificate that is has locally.