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.
This guide will provide step by step directions on how to integrate an organization's identity provider into the Grid such that the organizations users may use their existing credentials in the Grid. This guide is intended for software developers, a technical understanding of the Authentication Service and Dorian is recommended.
Dorian provides an integration point between external security domains and the grid, allowing accounts managed in external domains to be federated and managed in the grid. This allows user's to use their organizational provided credentials or the credentials they use every day to "logon" to the Grid. To enable this an organization's Identity Provider (IdP) or the system that issues credentials to users must be integrated with Dorian.
To integrate an Identity Provider with Dorian, the Identity Provider must be able provide a SAML Assertion for its users each time they authenticate with the Grid. The SAML assertion must contain an Authentication Statement asserting that the user has authenticated with the Identity provider and by what means they used to authenticate. The SAML Assertion must also contain an Attribute Statement asserting the following attributes:
- User's Identity with the IdP
- First Name
- Last Name
- Email Address
The SAML assertion identifies the user, proves that they authenticated with the IdP, and provides a small set of information about the user which is useful for Dorian administrators. For complete details on the SAML Assertion required by Dorian please consult the technical specification.
The Authentication Service provides a framework for issuing SAML assertions for existing credential providers such that they may easily integrated with Dorian and other grid credential providers. The authentication service also provides a uniform authentication interface in which applications can be built on. Integrating an organization's identity provider into the Grid requires standing up and Authentication Service for that organization. In this guide we will provide an overview on how to stand up an Authentication Service for an Identity Provider.
The figure to the right 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.
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:
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. 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:
The Default Authentication Provider delegated the authentication of users to a SubjectProvider. 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 who in turn issues the SAMLAssertion and signs it.
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:
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:
- gov.nih.nci.security.authentication.principal.LoginIdPrincipal - The user's unique user id within their organization's identity provider.
- gov.nih.nci.security.authentication.principal.FirstNamePrincipal - The user's first name.
- gov.nih.nci.security.authentication.principal.LastNamePrincipal - The user's last name.
- 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:
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.
The SAMLProvider defines a java interface for issuing SAML Assertions to the AuthenticationProvider. The interface is define in the class:
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:
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.
The Authentication Service provides many integration points for integrating an identity provider. Below is a a list of the most common approaches including a description on when to take the approach. For each of the approaches listed below, we have provided a step by step guide for implementing the approach.
This option should be used in the case where your Identity Provider is not capable of issuing SAML Assertions but is supported by the Common Security Module (CSM). For step by step instructions on using this approach click here.
This option should be used in the case where your Identity Provider is not capable of issuing SAML Assertions and is not supported by the Common Security Module (CSM). For step by step instructions on using this approach click here.
This option should used in the case where the Identity Provider being integrated has the ability to authenticate users and issue Dorian-compliant SAML Assertion. (i.e Shibboleth). For step by step instructions on using this approach click here.