View source for GCube Clients Integration with security

[[Category:Developer's Guide]]
__TOC__
==Overview==
GCube Client Security is implemented by the '''common-security''' library, based on the new ''Feather Weight Stack'' (FWS). An high level description of the library is provided in the section [[Integration_and_Interoperability_Facilities_Framework:_Client_Libraries_Design_Model#Security_Management|Client Security Library]], while more details can be found in [[SOA3 Connector]] section.

The library can be used both in GHNs and standalone clients. Standalone clients are integrated with ''common-security'' library and explicitly use it to set the required credentials (username/password, certificate of assertion id): it is up to the developer to define the way  the end user passes the credentials to the client (command line, configuration file...).

While GHNs transparently set the default credentials in outgoing messages by using the library: defaults credentials are [[SOA3 Connector#Ticket_based_Authentication|tickets]] for identity propagation ([[GCube Credentials]]). 

As said there is the possibility to use different credentials: in particular it is possible to configure the container to use only TLS ([[GHN Security Configuration]]). If more a specific behaviour is requested, for example if a  GHN should use its own Message Level Security credentials (username/password or assertion ID) for performing calls, it is possible to obtain it by modifying the code of the service in the same way as for standalone clients.

==Common Security Library==
The library is composed by two jars:

* <code>common-security.jar</code>
* <code>gcube-security-utils.jar</code>

both the jars are part of SOA3 connector and are part of the libraries of the container. They can also be used standalone because their only dependency is <code>common-gcore-stub</code> library, which is built on FWS stack.

The library provides two main interfaces:

* <code>CredentialManager</code>
* <code>Credentials</code>

The Interface ''CredentialManager'' defines a singleton [http://docs.oracle.com/javase/6/docs/api/java/lang/InheritableThreadLocal.html <code>InheritableThreadLocal</code>] Object with methods to <code>set</code>', <code>get</code> and <code>remove</code> the credentials for the current Thread. The ''InheritableThreadLocal'' feature allows the inserted Credential to be valid for this thread and its descendents till the next call to the method <code>set</code>.

The interface ''Credentials'' defines the nature of the objects containing the actual credentials, several implementations are provided:

* <code>X509TLSCredentials</code>, defining TLS and X509 based credential
* <code>UserNamePasswordCredentials</code>, for username/password based Message Level Security
* <code>FederatedCredentials</code>, for SAML Assertion ID based authentication
* <code>X509CombinedCredentials</code>, to be used in combination with another Credentials object to combine TLS with Message Level Security
* <code>Base64EncodedCredentials</code>, to be used in combination with another Credentials object to Base64 encode the Message Level Security data

==Use of the Library==
The Developer should only define the ''Credentials'' object and set it in the ''CredentialManager''. The FWS, in the background, will add the ''Credentials'' just before sending the message. It is important to remember that in gCube infrastructure Message Level Security data must be Base64 encoded.

For example, let's suppose to implement a client for a gCube Service ''sample'' using the credentials Username=''gCube'', Password=''gCube''. The code is the following:

 UserNamePasswordCredentials pureCredentials = new UserNamePasswordCredentials("gCube", "gCube".toCharArray());
 Base64EncodedCredentials encodedCredentials = new Base64EncodedCredentials(pureCredentials); //Base64 encodes the credentials
 CredentialManager.instance.set(encodedCredentials); //sets the credentials in the Credential Manager
 stub = stubFor(stateless).at(URI.create("http://localhost:9999/wsrf/services/acme/sample/stateless")); // creates the stub

More information on the use of the Credentials implementations can be found in the [[GCube Credentials]] page and on the library's javadocs.