Deploying SAML

Commercial products using SAML have been slow to appear. The following systems currently support SAML in production:

• Entegrity’s AssureAccess

• Entrust’s GetAccess portal

• Netegrity’s AffiliateMinder

• Securant’s RSA Cleartrust

• Sun’s iPlanet Directory Server with Access Management

• Sun’s ONE Network Identity

• Systinet’s WASP Secure Identity

A number of companies now provide toolkits to work with SAML and develop applications based on the single sign-on model. These include the Netegrity JSAML toolkit, and VeriSign’s Trust Services Integration Kit. These toolkits use their own APIs to implement SAML operations defined in the specification. However, there is currently a proposal for standardizing the APIs for Java, with the development of JSR 155: Web Services Security Assertions, through the Java Community Process (JCP). JSR 155 will implement all of the assertion operations defined in the specification, as well as provide guidance in the area of patterns for using SAML to develop applications. At the time of writing, JSR 155 is still under discussion and its recommendations have not been made public.

It also remains to be seen to what extent Microsoft will implement SAML in its products, because they already have a successful single sign-on technology called Passport. Although it is targeted at client/server Web-based applications, the success of Passport can be judged by the number of sites that now support its single sign-on authentication. These issues are not meant to dampen your enthusiasm for SAML— it’s just that as a developer, you need to be aware of the rapidly changing nature of Web Services!

VeriSign’s Trust Services Integration Kit

One of the more complete toolkits for working with SAML is the VeriSign Trust Services Integration Kit (TSIK). The TSIK is unique in that it provides a platform for creating trusted services and client/server applications, especially those that use Web Services. It provides access to many of the mandatory components required to support PKI, payments processing, XML digital signatures, XML messaging, and XML encryption. In addition, it now provides support for SAML to assert authentication and authorizations between security domains. The FAQ for the TSIK is at http://www.xmltrustcenter.org/developer/verisign/tsik/faq.htm , and a developer’s forum is at http://www .xmltrustcenter.org/developer/verisign/tsik/forum.htm.

The Java API provided with TSIK defines five major factory classes that can be used to process assertions:

• SOAPAssertionProviderFactory Produces AssertionProvider objects that connect to assertion authorities to retrieve Assertion objects, using SOAP.

• XMLAssertionGeneratorFactory Provides AssertionGenerator translator objects that map Assertion objects from XML.

• XMLRequestGeneratorFactory Provides RequestGenerator translator objects that map Request objects from XML.

• XMLResponseGeneratorFactory Provides ResponseGenerator translator objects that map Response objects from XML.

• XMLSecurityParameters Configures parameters for XML security.

Of the classes created by the factory classes, the AssertionProvider is probably the most significant, so an AssertionProvider example is examined in the next section.

Creating an AssertionProvider

An AssertionProvider is either an authentication authority (AuthNStatementProvider), attribute authority (AttributeStatementProvider), or PDP (AuthZDecisionStatement Provider). Each of these classes is specific to the provider type. In the more generic case, creating an AssertionProvider using the SOAPAssertionProviderFactory class is shown in the following Java code:

KeyStore k = KeyStore.getInstance(KeyStore.getDefaultType()); X509Certificate c = (X509Certificate) k.getCertificate("username"); PrivateKey pk = (PrivateKey) k.getKey("username", "password".toCharArray()); SOAPAssertionProviderFactory f = new SOAPAssertionProviderFactory(new URL("https://treefrog-onsite-fe.bbtest.net:8081/vspts/SamlResponder")); f.setSigningKey(new RSASigningKey(pk)); f.setVerifyingKey(new RSAVerifyingKey(c)); AssertionProvider p = f.newAssertionProvider(); 

In this example, a new KeyStore object is initialized and the X.509 certificate for the appropriate user is retrieved. The private key for the user is also retrieved when the appropriate password is supplied. The private key and certificate-embedded public key allow for signing and verifying, respectively. Next, a SOAPAssertionProviderFactory is instantiated, with a test URL in this instance. Next, the factory object is signed and verified, and a new AssertionProvider object p is created by invoking the newAssertionProvider() method.

Authentication

To create a query for authentication using Kerberos, the AuthNQuery class is instantiated as shown in the following example:

NameIdentifier n = new NameIdentifier("[e-mail]"); SubjectConfirmation c = new  SubjectConfirmation(Identifiers.AUTHN_METHOD_KERBEROS); Subject s = new Subject(n, c); Query q = new AuthNQuery(s, Identifiers.AUTHN_METHOD_KERBEROS);

Here, the NameIdentifier specifies a principal to be authenticated and the SubjectConfirmation class specifies how the authentication is to be undertaken (in this case, Kerberos is used). The Subject class combines elements of the NameIdentifier and SubjectConfirmation classes, in a form suitable for creating a new AuthNQuery object. The query can then be used in conjunction with an AssertionProvider to return the set of appropriate assertions from the server. To establish the authenticity of the authentication request, an Authenticity object is retrieved from the list of assertions by calling the isAuthentic() method. If required, an AuthNStatement object can be instantiated to retrieve the relevant details of the principal using the getSubject() and getNameIdentifier() methods.

Making an Attribute Query

A sample SAML AttributeQuery XML request is shown here, using Kerberos as the authentication method:

<samlp:AttributeQuery>       <saml:Subject xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">             <saml:NameIdentifier Format=""       NameQualifier="verisign.com/ams">joe.bloggs</saml:NameIdentifier>             <saml:SubjectConfirmation>             <saml:ConfirmationMethod>urn:ietf:rfc:1510             </saml:ConfirmationMethod>             <saml:SubjectConfirmationData>password             </saml:SubjectConfirmationData>             </saml:SubjectConfirmation>       </saml:Subject> <saml:AttributeDesignator AttributeName="//verisign.com/core/attr/ email" AttributeNamespace="verisign.com/ams/namespace/common"  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"/> </samlp:AttributeQuery>

Here, we can see that the AttributeQuery contains several elements, such as NameIdentifier and SubjectConfirmation, that help to identify the principal to whom the attribute request relates. SubjectConfirmation also contains elements like ConfirmationMethod, which in this instance specifies Kerberos (urn:ietf:rfc:1510). The following XML response would be provided from a server responding to this request:

<samlp:Status>       <samlp:StatusCode Value="samlp:Success"/> </samlp:Status>

Here, we can see that the request was successful. However, it’s also possible that a number of error codes could be returned, including the following:

• VersionMismatch Client and server are running different software versions.

• Requester There was an error on the client side.

• Responder There was an error on the server side.

• RequestVersionTooHigh Client’s protocol version is too new for the server to process correctly.

• RequestVersionTooLow Client’s protocol version is too old for the server to process correctly.

• RequestVersionDeprecated Client’s protocol version is no longer supported at all.

• TooManyResponses Maximum of possible returned elements has been exceeded.

• RequestDenied Request has been understood by the server but has been refused, possibly because of security concerns.

• ResourceNotRecognized Attribute query requested is not supported or it is invalid.

After the successful status has been returned in this example, the following authentication data is returned:

<saml:AuthenticationStatement AuthenticationInstant="2002-11-16T13:32:31Z"  AuthenticationMethod="Kerberos">       <saml:Subject>             <saml:NameIdentifier  NameQualifier="verisign.com/ams">jbloggs</saml:NameIdentifier>       </saml:Subject> </saml:AuthenticationStatement> 

Here, we can see that the NameIdentifier for jbloggs has been returned. Now the AttributeData is returned:

<saml:AttributeStatement>       <saml:Subject>       <saml:NameIdentifier NameQualifier="verisign.com/ams">jbloggs</saml:NameIdentifier>        </saml:Subject>      <saml:Attribute AttributeName="//verisign.com/xas/attr/ contactInfo" AttributeNamespace="verisign.com/ams/namespace/common">       <saml:AttributeValue> me> <lastName>Bloggs</lastName> <emailAddress>[e-mail]</emailAddress> </contactInfo>       </saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> </saml:Assertion>

Here, we can see in the raw XML the various tokens associated with this principal’s AttributeValue, including the contactInfo element, with the tokens firstName, lastName, emailAddress, and telephoneNumber.

Let’s look at the client code required to process the response. The AttributeStatement object is instantiated, which contains specific attributes for the principal, and even their Role-Based Access Control (RBAC) authorizations. By invoking the getAttributes() method of an AttributeStatement object, when the attributes are returned in the response from the server, they can be displayed by calling the getAttributeName()and getAttributeValues() methods of the Attribute class in a display like this:

Name 1: //verisign.com/core/attr/first_name Value 1: Joe Name 2: //verisign.com/core/attr/last_name Value 2: Bloggs Name 3: //verisign.com/core/attr/email Value 3: [e-mail] Name 4: //verisign.com/core/attr/phone_number Value 4: 02-9999-8888 Name 5: //verisign.com/core/attr/organization_name Value 5: iBuyStocks.com Name 6: //verisign.com/core/attr/department Value 6: Consumer Name 7: //acme.com/role Value 7: Client 

In this example, seven names and values were returned.