esoc European Space Operations Centre Robert-Bosch-Strasse 5 64293 Darmstadt Germany Tel: (49)615190-0 Fax: (49)615190485 www.esa.int SSA DC-I Part 1 - Single Sign-On and Access Management ICD Prepared by Vincenzo Mario Todisco Reference SSA-DC-SW-ICD-0001 Issue 2 Revision 1 Date of Issue 24/8/2012 Status Final Document Type ICD Distribution Daniel Fischer Gaspard Gendreau Gian Maria Pinna Gianpiero Di Girolamo Giulio Maira Serge Moulin Vicente Navarro Fabrizio Giordano
Title Issue 2 Revision 1 Author Vincenzo Mario Todisco Approved by Date 24/8/2012 Date Gianpiero Di Girolamo 01/09/2012 Reason for change Issue Revision Date First draft for CDR 1 0 16/02/2011 D1 delivery with application of CDR RIDs 1 1 18/03/2011 Delivery for D2 2 0 25/01/2012 Final delivery 2 1 24/08/2012 Issue 1 Revision 0 Reason for change Date Pages Comment First draft for CDR 16/02/2011 all - Page 2/22
Issue 1 Revision 1 Reason for change Date Pages Comment DC1_P1_r#37 18/03/2011 8 17 section 4 modified section 6 added Issue 2 Revision 0 Reason for change Date Pages Comment Final decision about SMT 25/01/2012 11 and foll. section 5 modified Issue 2 Revision 1 Reason for change Date Pages Comment Format changed according to ESA standard template 24/08/2012 all - Page 3/22
Table of Contents 1 Introduction... 5 1.1 Context... 5 1.2 Purpose... 5 2 Applicable and Reference Documents... 6 2.1 Applicable Documents... 6 3 Terms, Definitions and Abbreviated Terms... 6 4 Software Overview... 8 5 Integration with SSA DC-I SSO... 11 5.1 Example of IDP and Service Provider configuration procedures... 12 5.1.1 Authentication method for an existing web application... 12 5.1.2 IDP and Service Provider installation and configuration... 13 5.2 Liferay Integration with OpenAM... 15 5.3 Knowledge Base... 16 6 Interfaces... 17 6.1 RESTful interfaces... 17 6.1.1 Authentication... 17 6.1.2 Logout... 18 6.1.3 Token Validation... 19 6.1.4 Token Attribute Retrieval... 19 6.2 OpenAM logout page URL... 21 6.3 OpenAM log-in interface (MMI)... 22 Page 4/22
1 INTRODUCTION 1.1 Context As highlighted in [SSA-CS-SW-TN-0001] while several Web Presence elements will be available in the SSA system, a homogeneous concept will be presented to the SSA users community and the general public. Since a number of users will use different applications from more than one segment (i.e. users may be interested in SWE and NEO services/applications), a central identity management system will be deployed. This set-up allows the deployment of a Single Sign-On (SSO) mechanism for the authentication service. Single Sign-On means that a user logs in once and gains access to all system applications (i.e. the precursor services applications and SMT) he is authenticated without being prompted to log in again at each of them. In the context of the SSA DC-1 project a Single Sign-On solution is one of the key architectural components, as it will be used by each of the segment specific web development/portal 1.2 Purpose This Interface Control Document aims at providing guidelines on how third party Web Applications can integrate with SSA DC-I Single Sign-On solution. The document shows how to integrate web applications based on the Apache Web Server, the most widely used in the world, and web applications based on Liferay/Glassfish server. Similar procedures apply for other web servers and application servers. The integration requires the installation of a service provider on the web server hosting the application needed. Furthermore information about the service provider needs to be stored in the central SSO system. The service provider will be responsible for intercepting the user request and redirect to the SSO login form in the case the user is not authenticated. The need for the installation of the service provider justifies the tailoring of the ICD. Such a tailoring consists of a chapter, the fifth, dedicated to the integration with SSA DC-I SSO. Page 5/22
2 APPLICABLE AND REFERENCE DOCUMENTS 2.1 Applicable Documents Ref. Document Title Reference AD-001 AD-002 Technical Web Portal High-Level Components Description SSA DC-I Part 1 - ICT Support to Pilot Data Centre Implementation - Statement of Work SSA-CS-SW-TN-0001 SSA-CO-SOW-0001 AD-003 ECSS-E-ST-40C Space Engineering: Software ECSS-E-ST-40C 3 TERMS, DEFINITIONS AND ABBREVIATED TERMS Acronym CMS DC FQDN ICD IDP NEO PEP SMT SP SSA SSO Description Content Management System Data Centre Full Qualified Domain Name Interface Control Document Identity Provider Near Earth Objects Policy Enforcement Point Service Management Tool Service Provider Space Situational Awareness Single Sign On Page 6/22
Acronym SWE Description Space Weather Page 7/22
4 SOFTWARE OVERVIEW The concept of a centralised SSO and Identity Management solution is shown in the figure below. Third party Web Applications must interact with the centralized system for the initial authentication but have their own access control DB. Figure 4-1 SSA Single Sign On Concept OpenAM is the open source software that will provide the Identity Management System including the authentication mechanism for the entire project. The main goal of the SSA DC-I activity is to implement the architecture shown in the following page. Page 8/22
HTTP/HTTPS HTTP/HTTPS OpenAM Interface OpenAM Business/Presentation LDAP Liferay Portal SMT SQLNet SQLNet LDAP Interface Persistence OpenDS Liferay DB (MySQL) MySQL Connector SMT DB (MySQL) MySQL Connector SSA Identity Management System SSA Technical Web Portal SSA Service Management Tool Figure 4-2 SSA Single Sign On System Architecture The main components of the OpenAM architecture are: Directory Service (OpenDS) IDP or Identity Provider (OpenAM) SP or Service Provider (OpenAM Web policy agent) The diagram below shows the processing steps of SSO using session cookies with authorization policy enforced. Page 9/22
4-3: Access to protected resource Page 10/22
5 INTEGRATION WITH SSA DC-I SSO The basics steps of the integration with the centralized SSO system can be divided in two groups: OpenAM Server (IDP) Configuration Third party Web Server side Configuration. The first group has to be executed by the OpenAM Administrator with the parameters provided by the Third Party application Administrator. The second group has to be executed by the Third Party application Administrator. OpenAM Server (IDP) configuration 1 1. Create users, whose details have been provided by the third party application Administrator 2. Creating Web Policy Agent Profile. The following parameters have to be provided by Third Party application administrator (see section 3.1 IDP Side for an example of detailed procedure): a. Web Agent Name (e.g. webagent) b. Password c. Server URL (e.g. http://openam.example.com:8080/openam) d. Agent URL (e.g. http://webserver.example.com:80) 3. Creating an Access Policy. Each policy will apply a set of rules to a set of subjects (users or groups), potentially in a given a set of conditions. These rules can then allow (or deny) access to certain resources held on the web server. a. Access Policy Name (e.g. URLPolicy) Resource to be protected: (http://webserver.example.com/*) Actions (e.g. Select and allow both GET and POST) 1 For more information please refer to https://wikis.forgerock.org/confluence/display/openam/openam+server+configuration Page 11/22
b. Specify which user has access to the early configured Resource Web Server Configuration 2 1. Install a Web Policy Agent onto the web server: a. Download the Web Policy Agent from http://www.forgerock.com/downloads.html b. Install the Web Policy Agent (see section 5.1 SP side for a detailed procedure on Apache/Linux environment) 2. Testing: try to access a protected resource on the web server, by going to http://website.example.com. This should redirect to the login page for OpenAM, with a redirect argument in the address bar for the web server. Log in with the credentials that have the right to view this resource. This should then redirect to the website hosted on the web server. 5.1 Example of IDP and Service Provider configuration procedures 5.1.1 Authentication method for an existing web application Here we assume a web application having Apache as frontend. Normally a web application allows a SSO integration having as configuration option the possibility to enable the HTTP Basic Authentication that relies on the mod_auth Apache module. Enabling this authentication method means to declare that the application trusts that the user accessing it has been already authenticated. SSL/TLS could be used in order to provide a security layer. The application recognises the authenticated user because after the authentication against the IDP (OpenAM) a session variable has been set that contains the username of the person accessing the system. The username is known by the application and thus this can apply the authorizations configured in its context. 2 For more information please refer to https://wikis.forgerock.org/confluence/display/openam/web+server+configuration Page 12/22
This concept can be applied to every application and even to every web server container that has the HTTP Basic Authentication functionality. 5.1.2 IDP and Service Provider installation and configuration In the context of this project we have configured one Service Provider based on apache and in particular the itop ticketing system. This chapter provides the instruction followed to install the OpenAM policy agent and its configuration. The main reference for the documentation is: https://wikis.forgerock.org/confluence/display/openam/web+server+configuration Requirements It is assumed that the system will be set up in order to fulfil the following requirements: Java 6 installed Apache 2.2 installed Software package apache_v22_linux_agent_3.zip available root password is known OpenAM amadmin password is known OpenAM is up and running Installation/Configuration 5.1.2.1 IDP side 1. Login on the service provider as root 2. Login to OpenAM as amadmin 3. goto Access Control --> Agents 4. Create a new agent into the realm using OpenAM admin tool: a. set agent name (e.g. itopagent) b. set agent password Page 13/22
c. set OpenAM service url: (e.g. http://sso.serco.eu:80/openam_s951) d. set service provider agent (itop) URL(e.g. http://itop.eng.serco.eu:80) 5. Click on Create 6. Click on the new agent to open details page 7. Ensure that the SSO Only check is enabled 8. Ensure that FQDN check in Agent configuration Global tab is disabled 9. Ensure that CDSSO in Agent configuration SSO tab is disabled 5.1.2.2 SP side (only the first time) 1. Store the password for the agent just created into /var/tmp/passwd (the password is needed just for the installation of the agent, after the reboot will be deleted) 2. Unzip the software package (apache_linux_agent) under /usr 3. Go into /usr/web-agents/apache22_agent/bin 4. Run./agentadmin --install 5. Specify the apache config folder (e.g. /etc/httpd/conf or /etc/apache2 ) 6. Specify url of the SSO (e.g. http://sso.eng.serco.eu/openam_953) 7. Specify the service provider url (ex. http://itop.eng.serco.eu:80) 8. Specify the agent name (itopagent) 9. Specify the path of the file where the password is stored (/var/tmp/passwd) 10. Confirm and proceed with the installation Note: the installation puts an "include" directive into the httpd.conf file pointing to the agent configuration file/s 5.1.2.3 SP side integration of custom application The OpenAM policy agent provides an integrated plug-in that uses the interfaces exposed by the IDP Page 14/22
In order to complete the integration of an application having the apache running on the SP as front-end, it is necessary to identify the user authenticated to manage the access to the application functionalities. The policy agent complies with the HTTP Basic authentication, thus filling-in some global variables. The following table summarize the key information to be used for the integration of a custom application. Attribute name REMOTE_USER AUTH_TYPE iplanedirectorypro Description String used as username in the login form OpenSSO fixed value Token id of the current user session The value of the attributes can be retrieved using the following examples for the most common languages: Java: request.getremoteuser() PHP: _SERVER[ REMOTE_USER ] As explained in the following sections the value of the iplanedirectorypro variable can be used to check if the session is valid and to re-initialize the idle time (used to extend current session). 5.2 Liferay Integration with OpenAM The following procedure is specific for web applications developed in Liferay. The procedure is independent from the application server on which Liferay is installed. In our example GlassFish has been used. 1. Login to Liferay with admin account 2. Open the portal control panel 3. Click on "settings" 4. Click on "authentication" 5. Click on "opensso" Page 15/22
a. set the login URL (e.g. http://sso.serco.eu/openam_953/ui/login?goto=https://ssa.serco.eu /group/ssa/home) b. set the logout URL (e.g. http://sso.serco.eu/openam_953/ui/logout?goto=https://ssa.serco.e u/web/ssa/home) c. set the service URL (e.g. http://sso.serco.eu/openam_953) d. set the Screen Name Attribute: [uid] e. set the Email Address Attribute: [mail] f. set the First Name Attribute: [givenname] g. set the last name Attribute: [sn] h. check the configuration by pressing the button Test OpenSSO Configuration i. if check is OK tick the box Enabled and click on Save button 5.3 Knowledge Base In this section it will be indicate how to trouble-shoot the most frequent problems Issue redirection to IDP does not work or loops continuously Solution Specify the goto parameter into Login URL in Agent configuration OpenAM Services tab and rename the existing goto parameter to goto2 Page 16/22
6 INTERFACES This section describes the interfaces design of the software. The following entities participate in messages exchange: The client s browser A proxy client which implements the relevant functionality of a browser to be compatible with OpenAM. The protected resource: which may be an HTML page, a Java servlet, Perl script, or any resource accessed through a URL via the HTTP protocol. No distinction is made with respect to data (static) and service (dynamic) resources. The Service Provider (SP): which operates services accessible via URLs over HTTP and HTTPS The OpenAM Agent: The task of this component is to protect resource URLs where UM-SSO login is required. IDP or OpenAM Authentication Server: It is possible to authenticate to OpenAM using the authentication service 6.1 RESTful interfaces Several RESTful API are available that can perform the following functionalities: Authenticate Logout Token Validation Authorization Token Attribute Retrieval 6.1.1 Authentication Page 17/22
Initiator: proxy client or client s browser Endpoint: OpenAM IDP It is possible to authenticate to OpenAM using the authentication service. In its most basic form this can be done with a request in the following format: http://<openam_host>:<port>/<deploy_uri>/identity/authenticate?username=<uname>&password=<passwd> This request returns a token in the format: token.id=aqic5wm2ly4rfckcedfzxgrgvyevbkr-sgbkuemf4cmm5qg.*aajtsqabmde.* In order to authenticate against a different realm or service then the attributes which would normally be included as part of the /UI/Login instead need to be added to a 'uri=' parameter, for example: http://<openam_host>:<port>/<deploy_uri>/identity/authenticate?username=<uname>&password=<passwd>&uri=realm=<realm _name>&service=<authchain> In the case of a failed login, the rest interface may return either a UserNotFound or an InvalidPassword exception. Parameter username password uri Description defines the user to be authenticated defines the password of the user to be authenticated is optional and defines one or more URL parameters, e.g. a different realm or a service/authentication chain 6.1.2 Logout Initiator: proxy client or client s browser Endpoint: OpenAM IDP Page 18/22
Logout is simply a matter of passing the tokenid to the logout process. This means the logout is done using: http://<openam_host>:<port>/<deploy_uri>/identity/logout?tokenid=aqic5wm2ly4rfckcedfzxgrgvyevbkr- SgBkuemF4Cmm5Qg.*AAJTSQABMDE.* which will then invalidate the tokenid, and end the associated session. Parameter tokenid Description that represents the user to be logged-out 6.1.3 Token Validation Initiator: proxy client Endpoint: OpenAM IDP To validate tokens is another basic operation that the OpenAM RESTful interface offers. This is offered by the istokenvalid method: http://<openam_host>:<port>/<deploy_uri>/identity/istokenvalid?tokenid=aqic5wm2ly4rfckcedfzxgrgvyevbkr- SgBkuemF4Cmm5Qg.*AAJTSQABMDE.* This will either return boolean=true, in the case that it is a valid token, or return an HTTP- 401 in the case of a failure. If the returned value is true the idle time of the session is set back to 0 : this feature can be used to extend the current session if not already expired. Parameter tokenid Description represents the user to be validated 6.1.4 Token Attribute Retrieval Page 19/22
Initiator: proxy client Endpoint: OpenAM IDP The attribute retrieval interface, called attributes, allows all the attributes for a given subjectid token to be retrieved. This request is made up of only the subjectid parameter. An example request would be: http://<openam_host>:<port>/<deploy_uri>/identity/attributes?subjectid=aqic5wm2ly4rfckcedfzxgrgvyevbkr- SgBkuemF4Cmm5Qg.*AAJTSQABMDE.* Which would retrieve all of the attributes for a user in name-value pairs as shown below: Page 20/22
userdetails.token.id=aqic5wm2ly4sfczjtktqsebe931z82m-sa-dtlpmeb3e5cy.*aajtsqacmde.* userdetails.attribute.name=uid userdetails.attribute.value=user2 userdetails.attribute.name=userpassword userdetails.attribute.value={ssha}zad+/pkjkkrhc/u/vyjdwapvot5hquisahw7qw== userdetails.attribute.name=sn userdetails.attribute.value=two userdetails.attribute.name=cn userdetails.attribute.value=user2 userdetails.attribute.name=entrydn userdetails.attribute.value=uid=user2,ou=people,dc=example,dc=com userdetails.attribute.name=givenname userdetails.attribute.value=user userdetails.attribute.name=inetuserstatus userdetails.attribute.value=active userdetails.attribute.name=dn userdetails.attribute.value=uid=user2,ou=people,dc=example,dc=com userdetails.attribute.name=objectclass userdetails.attribute.value=organizationalperson userdetails.attribute.value=person userdetails.attribute.value=sunidentityserverlibertyppservice userdetails.attribute.value=inetorgperson userdetails.attribute.value=sunfederationmanagerdatastore userdetails.attribute.value=inetuser userdetails.attribute.value=iplanetpreferences userdetails.attribute.value=iplanet-am-managed-person userdetails.attribute.value=iplanet-am-user-service userdetails.attribute.value=sunfmsaml2nameidentifier userdetails.attribute.value=top Parameter Description subjectid represents the user for which attributes have to be retrieved 6.2 OpenAM logout page URL In addition to the Logout RESTful interface in order to logout from the OpenAM session a logout page URL is available: Page 21/22
http://<openam_host>:<port>/<deploy_uri>/ui/logout The logout button of the Third Party application can refer to this URL in order to logout. An example of logout link: <a href=" http://<openam_host>:<port>/<deploy_uri>/ui/logout" class="button">logout</a> 6.3 OpenAM log-in interface (MMI) In its basic form the MMI login Interface is as shown in the following picture. The basic authentication requires only User Name and Password. 6-1: MMI login Interface Page 22/22