Access Keys:
Skip to content (Access Key - 0)

Authentication Service

Design

Table of Contents

Overview

The goal of the Authentication Service is to allow existing identity providers to be seamlessly integrated into a production Grid environment such that users that are registered with an identity provider may use their existing credentials to access resources on the Grid. The Authentication Service provides a uniform web service interface providing applications with a single approach for authenticating users across a federation. In other words if each organization provides an Authentication Service for their Identity Provider, then applications can be developed to authenticate users using the Authentication Service interface, allowing users from any identity provider to authenticate with any application.

When a user authenticates with the Authentication Service, the Authentication Service returns a SAML Assertion. The Security Assertion Markup Language (SAML) (OASIS n.d.) is an XML standard for exchanging authentication and authorization data between security domains, that is, between an identity provider (a producer of assertions) and a service provider (a consumer of assertions). The SAML Assertion provides the application or consumer of the assertion the following:

  1. Proof that the user successfully authenticated.
  2. The method that the user authenticated with.
  3. Attributes containing information about the user.

Additional details and information about the contents of the SAML Assertion will be discussed later in this document. Fundamentally the SAML Assertion can be understood as proof to its consumer that the user has successfully authenticated.

Figure 1: Authentication Service Overview

An enterprise Grid is essentially a collection of community provided resources exposed over a network in the form of web/Grid services. Like the web individual interactions between web and Grid services are stateless and each require a separate authentication. Most secure Grid services require users and/or other services to authenticate with them using Grid credentials, formally referred to as X.509 certificates and/or X.509 certificates. Grid credentials are cryptographic credentials that must be digitally signed by a trusted certificate authority. Most existing identity providers do not have the capabilities to issue grid credentials. To provide this capability and for many other reasons outside the scope of this document, a grid service named Dorian (Langella, et al. 2006) was developed. Dorian issues grid credentials to users that provide it a SAML assertion that is signed by an identity provider that Dorian trusts. Each grid credential issued by Dorian is bound to a local account existing in one of the identity providers Dorian trusts. Together the Authentication Service and Dorian provide a solution for federating identity in a grid environment, allowing users to use their existing credentials to access secure grid resources.

Architecture

Figure 2 depicts the high level architecture for the Authentication Service. Clients communicate with the authentication service through its web service interface using HTTPS. The web service implementation delegates all authentication requests to the AuthenticationProvider. The AuthenticationProvider is responsible for validating the credential provided and for creating and signing the SAML Assertion that proves that the authentication was successful. The Authentication Service is built using the spring framework, allowing any of it modules to be easily replaced with another implementation. The default AuthenticationProvider delegates the validation of the credential to the SubjectProvider. The SubjectProvider validates the provided credential with organization's identity provider and obtains the user attributes that are required to be in the SAML Assertion from the Identity Provider. The user attributes are returned to the AuthenticationProvider. The AuthenticationProvider provides these attributes to the SAMLProvider. The SAMLProvider is responsible for encoding the user attributes provided by the AuthenticationProvider into a SAML Assertion. The SAMLProvider creates and signs the SAML Assertion and returns it to the AuthenticationProvider. The AuthenticationProvider returns the SAML Assertion to the web service interface, which then returns it to the client that made the authentication request.

Partitioning the responsibility into three separate providers enables multiple integration options for identity providers. For example organizations whose Identity Provider can authenticate users and provide the required attributes but do not provide support for issuing SAML assertions should use the default AuthenticationProvider and SAMLProvider. They may be able to leverage the default SubjectProvider, if their identity provider is supported, otherwise the may choose to implement their own SubjectProvider. Another example would be if an organization's identity provider could already issue the required SAML Assertions. In this case the organization should provide their own implementation of the AuthenticationProvider and can ignore the SubjectProvider and SAMLProvider.

Figure 2: Authentication Service Architecture

Authentication Provider

The AuthenticationProvider defines a java interface for authenticating users and for issuing SAML Assertions proving that they successfully authenticated. The AuthenticationProvider is called directly by the web service implementation and is the top most integration point for the Authentication Service. The interface is defined in the class:

org.cagrid.gaards.authentication.service.AuthenticationProvider

The interface requires the implementation of two methods: (1) authenticate() and (2) getSupportedAuthenticationProfiles(). The authenticate() method takes a credential (org.cagrid.gaards.authentication.Credential) as input and returns a SAMLAssertion (gov.nih.nci.cagrid.opensaml.SAMLAssertion). The credential should be used to authenticate the user with their organization's identity provider. The SAML Assertion should contain proof that the user successfully authenticated and the required a set of user attributes, mainly the user's local user id, first name, last name, and email address. For detailed information on the content required in the SAMLAssertion please consult the SAML Assertion section of this document.

The getSupportedAuthenticationProfiles() method specifies the type of credentials that the AuthenticationProvider accepts as a valid means of authentication. This method does not require an input however returns a set (java.util.Set) of valid QName(s) (javax.xml.namespace.QName). Each QName corresponds to the XML schema definition for the credential. The getSupportedAuthenticationProfiles() methods is used by the web service implementation to inform clients on which types of credentials they may use to authenticate with the AuthenticationService.

The default implementation for the AuthenticationProvider is the class:

org.cagrid.gaards.authentication.service.DefaultAuthenticationProvider

The Default Authentication Provider delegated the authentication of users to a SubjectProvider (see Subject Provider). Upon successfully authenticating a user, the SubjectProvider provides the Default AuthenticationProvider with the attribute required to issue the assertion, which it in turns passes to a SAMLProvider (see SAML Provider) who in turn issues the SAMLAssertion and signs it.

Subject Provider

The SubjectProvider defines a java interface for authenticating users with an identity provider and for returning user attributes describing information about the user and how the user authenticated. The interface is defined in the class:

org.cagrid.gaards.authentication.service.SubjectProvider

The interface requires the implementation of two methods: (1) getSubject() and (2) getSupportedAuthenticationProfiles(). The getSubject() method takes a credential (org.cagrid.gaards.authentication.Credential) as input and returns a Subject (javax.security.auth.Subject). The credential should be used to authenticate the user with their organization's identity provider. Upon successfully authenticating the user, the SubjectProvider should create and return a Subject object. The Subject object should contain the following principles, each representing an attribute describing the user:

  1. gov.nih.nci.security.authentication.principal.LoginIdPrincipal - The user's unique user id within their organization's identity provider.
  2. gov.nih.nci.security.authentication.principal.FirstNamePrincipal - The user's first name.
  3. gov.nih.nci.security.authentication.principal.LastNamePrincipal - The user's last name.
  4. gov.nih.nci.security.authentication.principal.EmailIdPrincipal - The user's email address.

The getSupportedAuthenticationProfiles() method specifies the type of credentials that the AuthenticationProvider accepts as a valid means of authentication. This method does not require an input however returns a set (java.util.Set) of valid QName(s) (javax.xml.namespace.QName). Each QName corresponds to the XML schema definition for the credential.
The default implementation for the SubjectProvider is:

org.cagrid.gaards.authentication.service.DefaultSubjectProvider

The Default Subject Provider provides out of the box capability for authenticating users and obtaining user attributes with several existing identity providers. These include any identity providers that are supported by the Common Security Module (CSM). CSM is used to implement the Default Subject Provider. For more information on CSM and which identity providers it support please consult: http://ncicb.nci.nih.gov/NCICB/infrastructure/cacore_overview/csm

SAML Provider

The SAMLProvider defines a java interface for issuing SAML Assertions to the AuthenticationProvider. The interface is define in the class:

org.cagrid.gaards.authentication.service.SAMLProvider

The interface requires the implementation of a single method, getSAML(). To issue a SAML Assertion the getSAML() method requires a subject (javax.security.auth.Subject) object containing the principles or user attributes needed to issue the SAML Assertion. SAML Assertions issued by the getSAML() method are returned as SAMLAssertion (gov.nih.nci.cagrid.opensaml.SAMLAssertion) objects.

The default implementation for the SubjectProvider is:

org.cagrid.gaards.authentication.service.DefaultSAMLProvider

The Default SAML Provider provides an out of the box solution for issuing the required SAML Assertions. The Default SAML Provider uses a user configured certificate and private key for issuing and signing SAML assertions. In cases where the Identity Provider does not have the ability to issue SAML Assertions, the Default SAML Provider will suffice the majority of the time.

Web Service Interface

The AuthenticationService's web service interface defines a technical specification on how to interact with the AuthenticationService. Clients communicate with the AuthenticationService over HTTPS using its web service interface. This section provides a high level overview of the operations and metadata that are supported in the AuthenticationService's web service interface. For the complete specification of the Authentication Service's web service interface please consult:

Authentication Service WSDL

Operations

authenticateUser

Allows a client to authenticate with the Authentication Service. This operation requires the client to specify a credential to authenticate with. If the authentication is successful, the AuthenticationService will create, sign, and return a valid SAML Assertion. If the authentication is unsuccessful an appropriate error message will be returned.

When authenticating a client may specify any credential that is supported by the Authentication Service. Clients can determine which credentials are supported by the Authentication Service by obtaining the AuthenticationProfiles metadata from the AuthenticationService. The AuthenticationProfiles element is defined in the XML schema http://gaards.cagrid.org/authentication*. The AuthenticationProfiles element provides a list of QName elements. Each QName represents the namespace and name of an XML schema element that specifies a credential type. A credential type is any XML Schema element that extends from the Credential element defined in the schema http://gaards.cagrid.org/authentication*. For example the schema, ***http://gaards.cagrid.org/authentication* specifies the *BasicAuthentication credential.

authenticate

This operation requires the client to specify a credential to authenticate with. If the authentication is successful, the AuthenticationService will create, sign, and return a valid SAML Assertion. If the authentication is unsuccessful an appropriate error message will be returned. This operation is DEPRECATED in version 1.3 of the Authentication Service; this operation was previously used in versions 1.0, 1.1, and 1.2 of the Authentication Service. In the future this operation will not be supported, where possible efforts should be made to use the authenticateUser() operation.

The credential accepted by this operation has been DEPRECATED. It is defined in the DEPRECATED schema http://cagrid.nci.nih.gov/1/authentication-service* in the element *Credential. The Credential element has two sub elements (1) BasicAuthenticationCredential and (2) CredentialExtension. The BasicAuthenticationCredential can be used to authenticate with a username and password. The CredentialExtension element provides an extension point to support other methods of authenticating. The CredentialExtension element is no longer supported by the AuthenticationService, the new authenticateUser() operation should be used.

getServiceSecurityMetadata

This operation provides the client with the security information it needs to connect to the service. This operation is supported by all caGrid services, allowing clients to dynamically determine the security requirements for a service such that they may configure themselves to appropriately connect to the service. For additional information on Security Metadata please consult the caGrid service specification document. (Hastings 2007).

GetResourceProperty

This method allows a client to obtain a specified resource property of metadata. For a list of resource properties or metadata supported by the AuthenticationService please consult the Metadata section of this document.

QueryResourceProperties

This method allows a client to query for a list of resource properties or metadata. For a list of resource properties or metadata supported by the AuthenticationService please consult the Metadata section of this document.

GetMultipleResourceProperties

This method allows a client to obtain a specified list of resource properties or metadata. For a list of resource properties or metadata supported by the AuthenticationService please consult the Metadata section of this document.

Metadata

Web/Grid services provide metadata or resource properties that describe various aspects of the service. In this section we will provide a description of each of the metadata components or resource properties that are supported by the AuthenticationService.

AuthenticationProfiles

The AuthenticationProfiles metadata element specifies which authentication profiles the Authentication Service supports. An example of an authentication profile is username and password, another example is the Public Key Infrastructure (PKI) which uses X.509 certificates and private keys for authentication. The AuthenticationProfiles metadata element is defined in the XML schema, http://gaards.cagrid.org/authentication* and is represented by the *AuthenticationProfiles element. The AuthenticationProfiles element provides a list of QName elements. Each QName represents the namespace and name of an XML schema element that specifies a credential type. A credential type is any XML Schema element that extends from the Credential element defined in the schema http://gaards.cagrid.org/authentication*. For example the schema, ***http://gaards.cagrid.org/authentication* specifies the *BasicAuthentication credential.

Each QName listed in the AuthenticationProfiles metadata represent a authentication profile or credential that is supported by the AuthenticationService. In other words if the QName for a credential is listed in the AuthenticationProfiles metadata element, then that credential may used to authenticate using the Authentication Service's authenticateUser() operation.

ServiceMetadata

All caGrid Services are expected to publish a set of ServiceMetadata which details the functionality of the service, the institution providing it, and the points of contacts. Full details on the ServiceMetadata can be found in the caGrid Metadata Infrastructure Technical Guide. (Oster 2006)

SAML Assertion

When users authenticate, the Authentication Service issues a SAML Assertion which is used to obtain Grid credentials from Dorian . In this section we will provide an overview of the SAML Assertions that are issued by the Authentication Service and consumed by Dorian, for the complete specification please consult the Dorian SAML Specification. (Langella, SAML Specification, caGrid Dorian 2006) The SAML Assertion contains two parts; (1) Authentication Statement and (2) Attribute Statement. The Authentication Statement contains information about how and when the user authenticated. The Attribute Statement consists of a set of attributes that identify the user. Dorian requires four attributes: local user id, first name, last name, and email address. In order to facilitate interoperability with many differing IdPs, Dorian is flexible in the attributes it can accept from IdPs. Dorian abstractly defines the need for the attribute localUserId, first name, last name, and email address. Dorian requires the localUserId attribute because it requires that IdP have a way of uniquely identifying it users. Dorian does not care what an IdP calls its localUserId or the format of it. Since Dorian is flexible with regards to attributes, this specification is also flexible and will abstractly define the attributes required.

Client API

Version 1.3 of the authentication service provides two client APIs, (1) gov.nih.nci.cagrid.authentication.client.AuthenticationClient and (2) org.cagrid.gaards.authentication.client.AuthenticationClient. The first (gov.nih.nci.cagrid.authentication.client.AuthenticationClient) is the same client API that is supported in earlier versions of the authentication service. It communicates with the Authentication Service using the earlier supported and deprecated web service operations. Existing applications written against earlier versions of the Authentication Service client will continue to operate with the newer version of the client. As of version 1.3 this client has been DEPRECATED, it is recommend that where possible the org.cagrid.gaards.authentication.client.AuthenticationClient should be used.

The second client, org.cagrid.gaards.authentication.client.AuthenticationClient is new to version 1.3 of the Authentication Service. It communicates with both current and previous versions of the Authentication Service.

Works Cited

  • Hastings, Shannons. caGrid Service Specification. Technical Guide, Columbus: caBIG, 2007.
  • Langella, Stephen. SAML Specification, caGrid Dorian. Technical Specification, caBIG, 2006.
  • Langella, Stephen, Scott Oster, Shannon Hastings, Frank Siebenlist, Tahsin Kurc, and Joel Saltz. "Dorian: Grid Service Infrastructure for Identity Management and Federation." The 19th IEEE Symposium on Computer-Based Medical Systems. Salt Lake City, UT: IEEE, 2006. 756-761.
  • Oster, Scott. caGrid Metadata Infrastructure. Technical Guide, Columbus, OH: caBIG, 2006.
Last edited by
Stephen Langella (1212 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence