esoc - ESA Space Weatherswe.ssa.esa.int/DOCS/SSA-DC/SSA-DC-SW-ICD-0001.pdf · OpenAM is the open...

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

/22

SSA DC-I Part 1 - Single Sign-On and Access Management ICD

Date 24/8/2012 Issue 2 Rev 1


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 -

/22




Issue 1 Revision 1


DC1_P1_r#37 18/03/2011 8

17

section 4 modified

section 6 added

Issue 2 Revision 0


Final decision about SMT 25/01/2012 11 and foll. section 5 modified

Issue 2 Revision 1


Format changed according to ESA standard

template

24/08/2012 all -

/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

/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.

/22




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

/22




Acronym Description

SWE Space Weather

/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.

/22




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

/22




4-3: Access to protected resource

/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) 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

http://openam.example.com:8080/openam

http://webserver.example.com/

/22




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

http://www.forgerock.com/downloads.html

http://website.example.com/

/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

https://wikis.forgerock.org/confluence/display/openam/Web+Server+Configuration

/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

/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 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"

/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 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

/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

/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 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


/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.


tokenid that represents the user to be logged-out

6.1.3 Token Validation

Initiator: proxy client


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-


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.


tokenid represents the user to be validated

6.1.4 Token Attribute Retrieval

/22




Initiator: proxy client


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-


Which would retrieve all of the attributes for a user in name-value pairs as shown below:

/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


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:

/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

esoc - ESA Space Weatherswe.ssa.esa.int/DOCS/SSA-DC/SSA-DC-SW-ICD-0001.pdf · OpenAM is the open...

Documents

Transcript of esoc - ESA Space Weatherswe.ssa.esa.int/DOCS/SSA-DC/SSA-DC-SW-ICD-0001.pdf · OpenAM is the open...