2.3 Installation Procedure

coldwaterphewΔιακομιστές

17 Νοε 2013 (πριν από 3 χρόνια και 8 μήνες)

86 εμφανίσεις









ESAA2

SAML2 Java Service Provider Installation Guide





















Release:

First Draft

Date of this version:

16
-
Mar
-
12

Prepared By:

David

Rhee

Project Sponsor:

Amie Clisby & Simon Jackson

Document Version
Number:

V0.
1

ESAA2


SAML2 Java SP Installation Guide


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyright 2012 Hyro


Document Control



Change

History


T
his document is version controlled. Change
s are subject to approval and control procedures
.



Revision Date


Version No.


Summary of Changes

Author

16

March

2012

0.1

Initial draft

David Rhee











Approvals


Name

Title

Approval Signature

Date

Simon Jackson

Gen
-
i Project Director



Amie Clisby

Application Delivery Manager



Richard Cookes

Idaptive General Manager





Distribution


Recipient


Position

Company

Area of Primary
Focus

Simon Jackson

Gen
-
i Project Director

Gen
-
i

All

Amie Cli
sby

Application Delivery Manager

MoE

All

Richard Cookes

Idaptive General Manager

Hyro

All

David Pears

Idaptive Consultant

Hyro

All

Shane Willcocks

Technical ConsuItant

Infosys

All

Grayson Mitchell

Solution Architect

MoE

All

Chris Hillman

Business Anal
yst

MoE

All

Bino Yohannan

Senior Java Developer

MoE

All




Terminology


Term

Definition

MoE

Ministry of Education (New Zealand)






ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro


SSO

Single Sign On

Java Web Container

A servlet container implementation such as Apache Tomcat or JBoss

Reverse Proxy

A ha
rdware or software component that acts a
proxy or
relay for accessing
internal web applications via HTTP or HTTPS

JAR

Java Archive file


a compressed file containing Java classes

WAR

Web Application Archive


a Java web application file containing code
and
resources for a Java web application deployable on a Java Web Container

ESAA2

Education Sector Authentication and Authorization system






ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro


Information Sources


Date

Name

Subject

Reference






















ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro



Table of Contents

1

INTRODUCTION

................................
................................
................................
................................
......................

6

1.1

B
ACKGROUND

................................
................................
................................
................................
....................

6

1.2

T
ARGET
A
UDIENCE

................................
................................
................................
................................
.............

6

2

CONNECTION PROCESS
................................
................................
................................
................................
.......

7

2.1

C
ONTACT
D
ETAILS

................................
................................
................................
................................
..............

7

2.2

I
NSTALLATION
P
REREQUISITES

................................
................................
................................
.............................

8

2.3

I
NSTALLATION
P
ROCEDURE

................................
................................
................................
................................
.

9

2.3.1

Pre
-
installation information

................................
................................
................................
.........................

9

2.3.2

Acquire the template WAR file

................................
................................
................................
...................

9

2.3.3

Prepare network configuration and the reverse proxy for your application URL

................................
........

9

2.3.4

Configure and install the template application

................................
................................
............................

9

2.3.5

Upload your SPMetadata.xml file

................................
................................
................................
.............

12

2.3.6

Complete the configuration

................................
................................
................................
......................

12

2
.3.7

Test your application single
-
sign
-
on

................................
................................
................................
.........

13

2.3.8

Overlay template application to your existing application

................................
................................
.........

15

2.4

T
ROUBLESHOOTING

................................
................................
................................
................................
..........

17

2.4.1

Missing XML Parser libraries

................................
................................
................................
...................

17

2.4.2

Conflicting versions of Jar files

................................
................................
................................
.................

17
























ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page
6

of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro


1

I
ntroduction

1.1

Background

E
ducation
S
ector
A
uthentication and
A
uthorisation version
2

(ESAA2)

is a role based
I
dentity
and
Access M
anagement system

for the NZ education sector.

ESAA2 provides a consolidated directory
of education sector organisations and iden
tities; distributed (or “delegated”) administration of
identities, roles, and entitlements; and an authentication sub
-
system for education sector business
applications. Education sector users are able to log in to any business application protected by
ESAA
2 using the same set of “credentials” (ESAA2 user ID and password).

This Software Development Kit (SDK) document provides installation and configuration information
for the authentication sub
-
system. Specifically, it describes the installation and configur
ation of a
Service Provider (SP) component that couples tightly
with
and is hosted with an education sector
business application. The SP supports the interface between the business application and the
centrally hosted ESAA2 components.

SPs and their assoc
iated SDKs are available for a number of platforms. This SDK describes the SP
for the
Java

platform.

1.2

Target Audience


The audience for this document is:



Developers integrating education sector business applications with ESAA2.


Other documents describe ESA
A2 interfaces and the processes required to integrate business
applications with ESAA2.












ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page
7

of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro


2

Connection Process

2.1

Contact Details

The MoE
Sector Service Desk

(SSD) is the first point of contact for ESAA2 issues
.







ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page
8

of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro



2.2

Installation Prerequisites

The pre
-
requ
isites to install the Java Service Provider for ESAA2

are:



A web container implementing the Java Servlet 2.
4

specification
.



JDK 1.5+
.



A test environment that is accessible from

the

internet and has access to
the
internet
.







ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page
9

of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro



2.3

Installation Procedure

2.3.1

Pre
-
inst
allation information

You will need to download the IdP Metadata
. T
he URL will
be
provided in the registration
confirmation email.

Determin
e

the full URL of your
web application as it will accessed on the internet.

2.3.2

Acquire the template WAR file

Download

the

template war file:

esaa2
-
java
-
sp
-
template.zip
.

2.3.3

Prepare network configuration and
the reverse proxy for your application URL

You should configure any reverse proxy, firewall and network connectivity
for your web application to
be accessible and have access

to the internet.

The URL to your application should use HTTPS and any reverse proxy configuration and
connectivity

configured between the reverse proxy and

yo
ur Java web container.

2.3.4

Configure and i
nstall the template application

Unzip

esaa2
-
java
-
sp
-
templ
ate.zip


to the
target
folder for your web application
. You will need to
consult your web container/JEE server documentation to configure the folder.

Note if your application is already deployed in the web container, undeploy the application and
backup or
rename your application folder.

You will need to create a directory to hold the configuration and log files for your application.

Edit the <your_application_directory>/WEB
-
INF/web.xml, and change the target configuration
directory from the default ‘/sp
-
jav
a’ to your fully qualified directory:



<context
-
param>



<description>




Path to configuration files for OIOSAML
-
J



</description>



<param
-
name>oiosaml
-
j.home</param
-
name>



<param
-
value>




/sp
-
java



</param
-
value>


</context
-
param>


Start/restart th
e web container and and access your application URL, e.g., our example application
URL is:

https://win7x01.hyro.global/sp
-
shell
-
app






ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page


of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro


This URL must be accessible

from the internet.

Access the application via the browser:



Click on 'Configure the system her
e':









ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page


of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro


Configure
the template app
:


Set the Entity ID to the URL of the web application
, in our example, it is
:

https://win7x01.hyro.global/sp
-
shell
-
app


Download the IdP metadata from the URL provided during registration, e.g.:

https://
samltest.hyro.com/
openam/saml2/jsp/exportmetadata.jsp?entityid=


Save to

a

file and set the metadata in ‘Identity Provider Metadata’



Select your server certificate (for your application URL) or check the 'Create new self
-
signed
keystore?..' option.


Set the configuratio
n details (ensure to record them)
:


1.

Keystore Password:

password

2.

Organisation Name:

sp
-
shell
-
app

3.

Organisation URL:

https://win7x01.hyro.global/sp
-
shell
-
app

4.

Technical email contact
address:

<use your contact email provided during registration>

5.

Enable Art
ifact consumer

6.

EEnable Redirect consumer

<check these options>






ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page


of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro


7.

Enable SOAP Single Logout

8.

Enable POST Single Logout



Click on 'Configure system'
.

Click on 'Download zip file with all configuration files and certificates'
.

2.3.5

Upload your SPMetadata.xml file

Your SPMetadata.xml file is
in the zip file you downloaded previously, in:

metadata/SP/SPMetadata.xml

Instructions will be provided with your registration confirmation email to upload your SP metadata file
to ESAA2.

A confirmation email will be sent once
your file has been uploaded successfully.


2.3.6

Complete the configuration

Shutdown your application server
.

Edit /sp
-
java/oiosaml
-
sp.properties

(your sp configuration directory was set above)
, and set oiosaml
-
sp.assurancelevel to 0 (zero):

# Required authenti
cation level. 2=password, 3=certificate

oiosaml
-
sp.assurancelevel=0


Edit or create the properites file in <your_application_directory>/WEB
-
INF/classes/saml2
-
http
-
header.properties






ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page


of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro


This file is used to map your custom HTTP header variables for your applica
tion to the SAML2
attributes provided by ESAA2
, the default contents are
:


HTTP_ESAA_UUID=ESAA2_UUID

HTTP_ESAA_UID=ESAA2_UID

HTTP_ESAA_GIVENNAME=ESAA2_GIVENNAME

HTTP_ESAA_SURNAME=ESAA2_SURNAME

HTTP_ESAA_LOGGEDINCONTEXTID=ESAA2_LOGGEDINCONTEXTID

HTTP_ESAA_S
ECURITYROLES=ESAA2_SECURITYROLES


Table
1

-

Default HTTP Header Attributes

HTTP Header Attribute

Name



Standard SAML2 Attribute Name

Description

HTTP_ESAA_UUID

ESAA2_UUID

Universally Unique ID


a unique opaque
identifier defined
by
ESAA2

HTTP_ESAA_UID


ESAA2_UID

User ID

HTTP_ESAA_GIVENNAME


ESAA2_GIVENNAME

First Name

HTTP_ESAA_MIDDLENAME


ESAA2_MIDDLENAME

Middle Name

HTTP_ESAA_SURNAME


ESAA2_SURNAME

Surname

HTTP_ESAA_PREFERREDNAME

ESAA2_PREFERREDNAME

Full name

HTTP_ESAA
_LOGGEDINCONTEXTID

ESAA2_LOGGEDINCONTEXTID

Login context ID

HTTP_ESAA_LOGGEDINCONTEXTNAME

ESAA2_LOGGEDINCONTEXTNAME

Login context name


the
organizational/community name for the
associated community

HTTP_ESAA_SECURITYROLES

ESAA2_SECURITYROLES

Securit
y roles/entitlements for the
specific application


Restart
your web container
.


2.3.7

Test your application single
-
sign
-
on

Open the browser to

your application URL, e.g.:


https://win7x01.hyro.global/sp
-
sh
ell
-
app/



Login using a user account created via the OpenAM administration console:







ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page


of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro





Click on 'Page requiring login', you should be redirected to the IdP login page:






ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page


of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro



2.3.8

Overlay template application to your existing application

You must overlay your e
xisting application with the template application created previously.

This involves copying JAR files from WEB
-
INF/lib and copying the properties files from WEB
-
INF/classes and editing your existing web.xml file.

Copy the following directories from your te
mplate web application to your existing web application
folder:


WEB
-
INF/lib

WEB
-
INF/classes


Edit your existing web.xml and merge the following sections from template application’s web.xml,
note that /sp
-
java was changed to your specific installation in s
ection
2.3.4
.


<context
-
param>



<description>




Path to configuration files for OIOSAML
-
J



</description>



<param
-
name>oiosaml
-
j.home</param
-
name>



<param
-
value>




/sp
-
java



</param
-
value>






ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page


of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro



</context
-
param>


<context
-
par
am>



<description>




Name of the configuration dir for oiosaml



</description>



<param
-
name>oiosaml
-
j.name</param
-
name>



<param
-
value>




sp
-
app
-
shell



</param
-
value>


</context
-
param>



<listener>



<listener
-
class>dk.itst.oiosaml.sp.service.session
.SessionDestroyListener</listener
-
class>


</listener>





<servlet>



<servlet
-
name>SAMLDispatcherServlet</servlet
-
name>



<servlet
-
class>




dk.itst.oiosaml.sp.service.DispatcherServlet



</servlet
-
class>



<load
-
on
-
startup>1</load
-
on
-
startup>


</servlet>



<servlet
-
mapping>



<servlet
-
name>SAMLDispatcherServlet</servlet
-
name>



<url
-
pattern>/saml/*</url
-
pattern>


</servlet
-
mapping>



<filter>



<filter
-
name>LoginFilter</filter
-
name>



<filter
-
class>dk.itst.oiosaml.sp.service.SPFilter</filter
-
class>


</fil
ter>




<filter>



<filter
-
name>Saml2HttpHeaderMapFilter</filter
-
name>






ESAA2



SA䵌M Java SP Insta汬at楯i 䝵楤i

Page


of


Last Updated:
Sunday, 17 November 2013, 10:53 AM



Copyr楧it 2012 Hyro




<filter
-
class>com.idaptive.sp.httpheader.HttpHeaderServletFilter</filter
-
class>



<init
-
param>




<param
-
name>saml2_http_map_file</param
-
name>




<param
-
value>/saml2
-
http
-
header.prope
rties</param
-
value>



</init
-
param>


</filter>



<filter
-
mapping>



<filter
-
name>Saml2HttpHeaderMapFilter</filter
-
name>



<url
-
pattern>/*</url
-
pattern>


</filter
-
mapping>



<filter
-
mapping>



<filter
-
name>LoginFilter</filter
-
name>



<url
-
pattern>/*</url
-
pa
ttern>


</filter
-
mapping>


2.4

Troubleshooting

The Java SP installation was tested in JBoss 5.1.0.GA

and JDK 1.6.

Different web containers

and
JREs

may have issues with class loading.

2.4.1

Missing XML Parser libraries

The following Xalan and Xerces Jar files were r
emoved from the WEB
-
INF/lib directory for Java SP:


xalan
-
serializer.jar (Version 2.7.1)

xalan
-
xalan.jar (Version 2.7.1)

xerces
-
xercesImpl.jar (Version 2.7.1)


Your web container or JDK should have these libraries (or more recent versions) installed.

2.4.2

Confl
icting versions of Jar files

It is possible that the Java SP contains version of Jar files existing in your application when
overlaying your existing application.

Generally choose the later version and delete older versions of the same library.