Authentication in the Cloud using SAML

With so many software options available in the cloud, it is common for an organization’s services to be comprised of a mixture of off the shelf software as a service (SaaS) and custom applications running on one of the many platforms as a service (PaaS).  An essential requirement stemming from such a heterogeneous architecture is the need for a single common and consistent user authentication interface across all the applications.  It should improve the user experience by not requiring users to log into and maintain separate credentials for each application.  It should improve security by making it easier for an organization to enforce a single authentication policy (multi-factored, PKI client cert, etc) across all its applications.  It should improve productivity by decoupling the authentication implementation from each application allowing each application to focus on implementing its core functionality. 

What is SAML?

A solution for implementing this requirement is using the SAML authentication protocol to delegate user authentication in each application or service provider (SP) to a trusted third party system called an identity provider (IDP).  The typical SAML authentication process is initiated when a user requests a protected resource from any of the organization’s applications (service providers).  If the user is not authenticated, the service provider sends the user to the identity provider to authenticate.  After the user successfully authenticates, the identity provider sends the user back to the service provider with a signed SAML assertion containing a set of attributes it knows about the user such as an user identifier and email address.  When the service provider receives the SAML assertion, it verifies the signature on the SAML assertion to ensure it came from the identity provider and was not tampered with in transit.  This verification is done using the identity provider’s public signing key.  If the signature is valid, the service provider finds the attribute from the SAML assertion identifying the user (username, email, etc) and returns the requested resource if it determines that the user is authorized to access it.  The specific endpoint locations (URLs) on the identity provider and service provider that the user is sent to and keys used in this process are typically specified in metadata files that are exchanged between the identity and service providers during the initialization of both entities.  Since the user and messages are sent between these entities using HTTP redirects, this particular flow is referred to as the HTTP Redirect binding in SAML. 

SAML HTTP Redirect Binding

Another common binding is the HTTP POST binding, which uses JavaScript triggered HTML form submissions to send messages via HTTP POST.  It is possible for SAML message exchanges to use both HTTP Redirect and HTTP POST bindings in cases where the former cannot be used due to message length exceeding the maximum allowable URL length of a browser.  For example, if the SAML assertion returned from the identity provider contains many attributes, the SAML message exchange may use the redirect binding for the initial SAML authentication request, but POST binding for SAML response. 

There are many good SAML identity providers available as a service in the cloud to choose from.  The setup is similar across all of them and typically involves two steps.  First, to authenticate the organization’s users, the identity provider needs to know who the users are.  This is typically done by connecting the identity provider to the organization’s user database such as a directory server (LDAP, Active Directory, etc).  Second, for each application delegating to the identity provider for authentication, the identity provider needs to know where (callback URL) on each application to send the user and SAML assertion after the user successfully authenticates. 

Each application acting as a SAML service provider needs to perform two actions in the SAML authentication process.  First, it needs to send unauthenticated users to the identity provider to authenticate.  Second, it needs to parse and validate the SAML assertion that is sent back to it after the user successfully authenticates to the identity provider.  In this post, I will demonstrate how to do the latter using the OpenSAML 3 Java library. 

Working with SAML Metadata

To validate the signature on the SAML assertion from the identity provider, the service provider needs to get the identity provider’s public signing key.  The service provider can get this signing key from the identity provider’s metadata.

Example IDP Metadata XML

SAML metadata can contain one or more entity descriptors, each identified by an entity ID.  Each entity descriptor contains one or more role descriptors for each role the entity performs.  Typically, an identity provider’s metadata file will contain only one entity descriptor (<EntityDescriptor>) containing one role descriptor describing the identity provider (<IDPSSODescriptor>) including its keys and endpoints.  Each service provider needs to be configured with the entity ID of the identity provider it is using.

OpenSAML 3 classes for resolving metadata and credentials

The MetadataCredentialResolver class can be used to get the keys (Credential) from metadata for an entity based a set of Criterion (CriteriaSet) such as its role (IDPSSODescriptor) and entity ID.  The resolve method of MetadataCredentialResolver returns all Credentials for the identity provider so the service provider needs to iterate through and find the one used for signing. 

MetadataCredentialResolver credentialResolver = new MetadataCredentialResolver();
credentialResolver.setRoleDescriptorResolver(roleDescriptorResolver);
credentialResolver.setKeyInfoCredentialResolver(DefaultSecurityConfigurationBootstrap.buildBasicInlineKeyInfoCredentialResolver());
credentialResolver.initialize();

CriteriaSet criteriaSet = new CriteriaSet();
criteriaSet.add(new EntityIdCriterion("urn:my-idp"));
criteriaSet.add(new EntityRoleCriterion(IDPSSODescriptor.DEFAULT_ELEMENT_NAME));

Credential signingKey = null;

Iterator<Credential> it = credentialResolver.resolve(criteriaSet).iterator();
while (it.hasNext()) {
    Credential key = it.next();
    if (key.getUsageType() == UsageType.SIGNING) {
        signingKey = key;
    }
}

MetadataCredentialResolver uses an instance of BasicRoleDescriptorResolver to resolve role descriptors for a given entity. 

BasicRoleDescriptorResolver roleDescriptorResolver = new BasicRoleDescriptorResolver(metadataResolver);
roleDescriptorResolver.initialize();

BasicRoleDescriptorResolver uses an implementation of the MetadataResolver interface to resolve entity descriptors.  In this demo, HTTPMetadataResolver is used, which uses a HttpClient to get the metadata from an URL. 

HttpClientBuilder builder = new HttpClientBuilder();
HttpClient client = builder.buildClient();

HTTPMetadataResolver metadataResolver = new HTTPMetadataResolver(client, "https://my-idp/metadata");
metadataResolver.setRequireValidMetadata(true);
metadataResolver.setParserPool(XMLObjectProviderRegistrySupport.getParserPool());
metadataResolver.setId("myMetadataResolver");
metadataResolver.initialize();

Parsing and validating SAML Assertions

The SAML assertion is sent from the identity provider to the service provider in a SAML response (XML) that is base64 encoded and set as the value of the SAMLReponse request parameter.  HttpServletRequest is used get this value. 

String samlResponse = request.getParameter("SAMLResponse");

Base64Support is used to decode the response. 

byte[] decodedResponse = Base64Support.decode(samlResponse);

DocumentBuilder is used to create a Document object from the XML.

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
DocumentBuilder db = dbf.newDocumentBuilder();
Document document = db.parse(new ByteArrayInputStream(decodedResponse));

Unmarshaller unmarshalls the document’s response element into a Response object.

Element responseEl = document.getDocumentElement();
Unmarshaller unmarshaller = XMLObjectProviderRegistrySupport.getUnmarshallerFactory().getUnmarshaller(responseEl);
Response response = (Response)unmarshaller.unmarshall(responseEl);

The Assertion is get from the Response. 

Assertion assertion = response.getAssertions().get(0);

SAMLSignatureProfileValidator is used to validate that the Assertion’s signature conforms to the SAML profile of XML Signature. 

SAMLSignatureProfileValidator profileValidator = new SAMLSignatureProfileValidator();
profileValidator.validate(assertion.getSignature());

SignatureValidator is used to validate the signature using the identity provider’s signing key. 

SignatureValidator.validate(assertion.getSignature(), signingKey);

If validation passes, the Attributes from the Assertion can be used by the service provider to identify the user and make authorization decisions. 

List<Attribute> attributes = assertion.getAttributeStatements().get(0).getAttributes();