Certificates used in the installation

In the installation on our testbed, we created self-signed CA, which we used to create these certificates for 

• ca-server
• contrail-federation-api
• contrail-federation-web
• wildcard certificate for contrail-idp

Example: hostname egi-cloud5.zam.kfa-juelich.de

• contrail-ca-server CN: ca-server.egi-cloud5.zam.kfa-juelich.de
• contrail-federation-api CN: contrail-federation-api.egi-cloud5.zam.kfa-juelich.de
• contrail-federation-web CN: contrail-federation-web.egi-cloud5.zam.kfa-juelich.de
• wildcard certificate for contrail-idp CN: *.contrail-idp.egi-cloud5.zam.kfa-juelich.de

Should installation be seen from outside, you should add additional entries into DNS server - if  egi-cloud5.zam.kfa-juelich.de  is a server running federation services, you need also an entry in DNS zones file for subdomains:

Hostnames used in the installation:

• ca-server.domain - Contrail CA
• contrail-federation-api.domain - Contrail Federation API
• contrail-federation-web.domain - Contrail Federation Web
• *.contrail-idp.domain - Contrail IdP (SimpleSAMLphp)
  • google.contrail-idp.domain - Contrail IdP (google auth)
  • federation.contrail-idp.domain - Contrail IdP (SAML2 auth - federation auth source)

In integration tests we used domain = contrail.eu (added in  /etc/hosts  on the servers and clients).

Create new CA (self signed):
# openssl req -newkey rsa:2048 -nodes -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

Generate new host certificate (e.g. for contrail-federation-web) with serial number 1:
# openssl genrsa -out contrail-federation-web.key 2048
# openssl req -new -key contrail-federation-web.key -out contrail-federation-web.req
# openssl x509 -req -in contrail-federation-web.req -CA ca.cer -CAkey ca.key -set_serial 1 -days 3650 -outform PEM -out contrail-federation-web.cert

We did the same for other servers: ca-server, contrail-federation-api and contrail-idp (this one should be wildcard certificate for *.contrail-idp.domain); see that serial numbers are unique.

Contrail CA Installation

Resources:
http://contrail.projects.ow2.org/xwiki/bin/download/Documentation/WebHome/InstallationGuide.pdf

Follow the installation procedure described in the Installation Guide, release 1.1., section 2.1.6 - Federation Certification Authority - Root CA and CA Server. In step 2 of the installation guide, use the certificate of the ca-server from step 1 of this guide.

If there is a /var/lib/tomcat6/webapps/ca/WEB-INF/lib/bcprov-jdk15-1.45.jar, delete this file and restart tomcat.

Contrail Federation API Installation

Resources:
http://contrail.projects.ow2.org/xwiki/bin/view/Documentation/federation-api

Set up 

• /etc/tomcat6/server.xml (see resources)
• /var/lib/tomcat6/webapps/federation-api/WEB-INF/web.xml (see resources)

Contrail Federation Web Installation

Resources:
http://contrail.projects.ow2.org/xwiki/bin/view/Documentation/federation-web

Set up 

• /etc/contrail/contrail-federation-web/federation-web.conf
  • ONLINE_CA_USE=True
  • ONLINE_CA_URI= <URI to CA Server>
• /usr/lib/contrail/federation-web/extra/remote_metadata.xml (see resources, you will need to change metadata according to changes on contrail-idp)

Contrail IdP Installation

Set servername and alias. Here, you need a wildcard certificate (for SSL support).

Change the content of the CAuth.php:
# Will be configurable...
STR1='http://localhost:8080/federation-id-prov/users/authenticate'
STR2='http://localhost:8080/federation-api/users/authenticate'
sed -i "s|$STR1|$STR2|" /usr/share/simplesamlphp-1.9.0/modules/contrailmodule/lib/Auth/Source/CAuth.php

Contrail Authentication Workflow

This is only to illustrate, how the installed components interact between each other to authenticate with the Contrail.

Detailed description:

authenticate()

User wishes to *authenticate()* to the portal.

chooseAuthSource()

User chooses the authentication source (google or shibb). Step
*chooseAuthSource()*.

authenticate()

User is redirected to external idp by simlplesamlphp.

After user enters her credentials, external idp returns attributes.
Step *authenticate()*.

mapAttributes(), lookup()

Attributes are mapped and looked-up with federation database.

Federation API and afterwards federation-idp returns userId.

Simplesamlphp appends Contrail's userId to attributes returned by
external idp and returns those as SAML assertion to the portal.

Steps *mapAttributes()* and *lookup()*.

authentication()

Portal asks federation-idp to return details about user with returned
userId (authentication(), "user" is returned).

Step *authentication()*.

login()

"Login" is done internally by federation-web (with returned "user"
document). 

getDelegatedCert()

CSR for delegated user's cert is created internally and
*getDelegatedCert()* is called on CA Server. 

CA server checks  with the federation-idp if the user really exists and
returns the delegated certificate back to the portal. *userExists()*

actions()

User starts using federation-api with Contrail's specific calls
(usage of the federation core which is out-of-scope of this diagram).

*actions()*