esoc - esa space weatherswe.ssa.esa.int/docs/ssa-dc/ssa-dc-sw-icd-0001.pdf · openam is the open...
TRANSCRIPT
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
ESA UNCLASSIFIED - For Official Use
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
Page 2/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
Title SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Issue 2 Revision 1
Author
Vincenzo Mario Todisco
Date
24/8/2012
Approved by 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 3/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 4/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 5/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 6/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
2 APPLICABLE AND REFERENCE DOCUMENTS
2.1 Applicable Documents
Ref. Document Title Reference
AD-001 Technical Web Portal High-Level Components
Description SSA-CS-SW-TN-0001
AD-002 SSA DC-I Part 1 - ICT Support to Pilot Data Centre
Implementation - Statement of Work SSA-CO-SOW-0001
AD-003 ECSS-E-ST-40C Space Engineering: Software ECSS-E-ST-40C
3 TERMS, DEFINITIONS AND ABBREVIATED TERMS
Acronym Description
CMS Content Management System
DC Data Centre
FQDN Full Qualified Domain Name
ICD Interface Control Document
IDP Identity Provider
NEO Near Earth Objects
PEP Policy Enforcement Point
SMT Service Management Tool
SP Service Provider
SSA Space Situational Awareness
SSO Single Sign On
Page 7/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
Acronym Description
SWE Space Weather
Page 8/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 9/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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.
SSA Identity Management System SSA Service Management ToolSSA Technical Web Portal
OpenDS
OpenAM
LDAP
Liferay Portal
Liferay DB (MySQL) MySQL Connector
SQLNet
OpenAM Interface
HTTP/HTTPS
SMT
HTTP/HTTPS
Persistence
Business/Presentation
SMT DB (MySQL) MySQL Connector
SQLNet
LDAP Interface
Page 10/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
4-3: Access to protected resource
Page 11/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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) configuration1
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 12/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
b. Specify which user has access to the early configured Resource
Web Server Configuration2
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 13/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 14/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 15/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 Description
REMOTE_USER String used as username in the login form
AUTH_TYPE “OpenSSO” fixed value
iPlaneDirectoryPro 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 16/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 Solution
redirection to IDP does not
work or loops continuously
Specify the goto parameter into Login URL in Agent configuration
OpenAM Services tab and rename the existing goto parameter to
goto2
Page 17/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 18/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 Description
username defines the user to be authenticated
password defines the password of the user to be authenticated
uri 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 19/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 Description
tokenid 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 Description
tokenid represents the user to be validated
6.1.4 Token Attribute Retrieval
Page 20/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 21/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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 22/22
SSA DC-I Part 1 - Single Sign-On and Access Management ICD
Date 24/8/2012 Issue 2 Rev 1
ESA UNCLASSIFIED - For Official Use
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