GCube Credentials

Overview

The SOA3 Framework provides APIs to manage several kinds of credentials and allows the gCube Nodes to communicate each other by propagating the identity of the original caller using a reference ticket. The original caller, that can be an user or a process (i.e. a service) can be identified by the following credentials:

• Username/Password, used especially by human callers
• SAML Assertion Id, for federated authentication
• X509 Certificate, used by human callers or by batch processes (i.e. services that needs autonomous authentication)

This section will briefly describe the supported credentials and show how to use them within the Client Security Library.

Credentials

SOA3 authenticates and authorizes requests based on the credentials of the caller: no explicit distinction between Message Level Security and Transport Level Security is done. However the integration layer combines TLS and MLS in the following way:

1. the Node checks autonomously the TLS signature of received HTTPS messages: if it is not valid, the process is interrupted and an unauthorized error is returned

2. the Node checks if any Message Level Credential is present in the received SOAP message. If it is found it's forwarded to SOA3 to check its validity: if it is valid, the message is authenticated, if it is not valid, an error is returned, if it is not found, the process goes to the point 3

3. the Node extracts the DN of the certificate used to sign the HTTPS request and sends it to SOA3

The communications between the Nodes and SOA3 are in HTTPS and the information flows using REST messages. The Message Level Credentials are sent by the clients to the Nodes in the security header of SOAP messages and the Portal, which contacts the service through the ASL works in the same way: the Common Security library adds the credentials to the outgoing requests.

Username/Password

SOA3 Framework supports common Username/Password authentication. Username and Password are set in the security header of the SOAP Message and currently are send in clear text (Base64 encoded): this means that HTTPS must be used to encrypt the communication and the credentials. When a gCube Node receives Username/Password credentials it sends a REST Access Request to SOA3: if the Access Request (authentication and authorization) succeeds, a ticket is returned. This ticket will replace the credentials if they needs to be propagated within the gCube infrastructure.

Username/Password and Common Security

The following piece of code shows how to set Username/Password credentials in a gCube client and encode them in Base 64.

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

Assertion ID

After a successful authentication on a federated domain, SOA3 produces an Assertion ID, identifying a SAML Assertion. The Assertion ID can replace Username/Password information in the header of the SOAP Message (in HTTPS). The authentication process on the Nodes is similar to Username/Password case: the Node receives the request and send the Assertion ID to SOA3 Server. SOA3 retrieves the Assertion, validates it and gets the attributes which are used for the authorization. If everything is OK a ticket is returned.

Assertion ID and Common Security

The following piece of code shows how to set Assertion ID credentials in a gCube client and encode them in Base 64.

FederatedCredentials pureFederatedCredentials = new FederatedCredentials("AssertionID");
Base64EncodedCredentials encodedCredentials = new Base64EncodedCredentials(pureFederatedCredentials); //Base64 encodes the credentials
CredentialManager.instance.set(encodedCredentials); //sets the credentials in the Credential Manager

X509 Certificate

X509 Certificates are used to sign and encrypt messages sent on HTTPS (Transport Level Security). In this case the security is implemented on a level lower than Message Level Security: this means that there is the possibility (and it is strongly encouraged) to use the combination of both TLS and MLS. For enabling HTTPS communications, gCube Nodes should be started in https mode, by using the script:

gcore-start-secure-container    

if MLS is enabled every Node will combine Username/Password, Assertion ID or Tickets with HTTPS, otherwise only HTTPS will be used.

X509 Certificate and Common Security

At client level, it is possible to enable https by using java standard security options or Common Security library. Java provides the possibility to use a keystore and a truststore, set through java properties:

javax.net.ssl.keystore
javax.net.ssl.truststore

The Common Security library provides a method more consistent with the rest of SOA3 Framework. In particular, the following piece of code sets X509 key and certificate (pem format) and the truststore directory:

X509TLSCredentials tlsCredentials = new X509TLSCredentials("certFilePath","keyFilePath","trustStoreDirPath","trustFilesExtension");
CredentialManager.instance.set(tlsCredentials); //sets the credentials in the Credential Manager

All the files must be in pem format and the key must be RSA encoded. The trust store directory must contain CA certificates in pem format with the extension of "trustFilesExtension". The fields are not mandatory and the default values are the following:

• certificate /etc/grid-security/hostcert.pem
• key /etc/grid-security/hostkey.pem
• trust directory /etc/grid-security/certificates
• extension .0

The Common Security library supports the combination of X509 certificates with any form of Message Level Security. The following piece of code shows how to obtain this:

Credentials anyCredential = new UserNamePasswordCredentials("gCube", "gCube".toCharArray());
X509CombinedCredentials tlsCombinedCredentials = new X509CombinedCredentials(anyCredential,"certFilePath","keyFilePath","trustStoreDirPath","trustFilesExtension");
CredentialManager.instance.set(tlsCredentials); //sets the credentials in the Credential Manager

The example above explains how to combine Username/Password credentials with Transport Level Security configured by code.

Ticket

As described on Tickets page, these credentials should not be managed by the developers because Nodes propagates them in background. However, in some case, it could be requested to use them. They are managed in the same way of the others:

TicketCredentials ticketCredentials = new TicketCredentials("ticket");
CredentialManager.instance.set(tlsCredentials); //sets the credentials in the Credential Manager

The format of the ticket is described in the section Identity propagation_based on tickets and is related to the instance of SOA3 which produced the ticket.

Interface Credentials

The Common Security library provides the interface Credentials which is implemented by the following classes already mentioned:

• UserNamePasswordCredentials
• FederatedCredentials
• X509TLSCredentials
• X509CombinedCredentials
• TicketCredentials

The interface provides the following methods:

• prepareCredentials: initializes the credentials to be included in the message
• disposeCredentials: performs the operations needed before removing the credentials
• getAuthenticationType: returns the credentials type (Username/Password, Federated, TLS or Ticket)
• getAuthenticationString: returns a string representation of the credentials
• getHeaderString: returns the credentials string for Message Level Security, null otherwise
• isPrepared: returns true if the credentials have been correctly initialized

By implementing the Credentials interface, it is possible to add further kinds of credentials