SAML2 PHP SP Installation Guide [Word; 1413kb]

waisttherapeuticSoftware and s/w Development

Nov 4, 2013 (4 years and 5 days ago)

155 views









ESAA2

SAML2
PHP

Service Provider Installation Guide





















Release:

First Draft

Date of this version:

29
-
Mar
-
12

Prepared By:

Yogesh

Puri

Project Sponsor:

Amie Clisby & Simon Jackson

Document Version
Number:

V0.
1

ESAA2


SAML2 PHP SP Installation Guide


Last Updated:
Tuesday, 5 November 2013, 4:29 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

29
March

2012

0.1

Initial draft

Yogesh Puri











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 Cl
isby

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 Ana
lyst

MoE

All

Bino Yohannan

Senior Java Developer

MoE

All




Terminology


Term

Definition

MoE

Ministry of Education (New Zealand)






ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro


SSO

Single Sign On

PHP

PHP

(recursive acronym for

PHP: Hypertext Preprocessor) is a widely
-
used
open source general
-
purpos
e scripting language that is especially suited for web
development and can be embedded into HTML.

IIS

Internet Information Services



is a

web server

application and set of feature
extension modules created by

Microsoft

for use with

Microsoft Windows
.

ID
P

Identity Provider



a web application that provides authentication and SSO in
the SAML2 specification

SP

Service Provider



a software agent that protects acess to a web application in
the SAML2 specification

ESAA2

Education Sector Authentication and

Authorization system

version 2

YourWebServer

IP /
DNS

Name or Alias name of your hosting machine where SimpleSAMLphp
is installed

OpenAMWebserver

IP /
DNS
Name or Alias name of your hosting machine where OpenAM or IdP is
installed






ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro


Information Sources


Date

Name

Subject

Reference






















ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i


Last Updated:
5/11/2013 4:29 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

Configure and install the template application

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

9

2.3.4

Configuring the SP

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

14

2.3.5

Adding IDPs to SP

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

18

2.3.6

Test your application single
-
sign
-
on

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

19

2.4

T
ROUBLESHOOTING

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

22
























ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page
6

of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro


1

Introduction

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 identities; distributed (or “delegated”) administration of
identities, roles, and entitlements; and an authentication sub
-
system for education sector bus
iness
applications. Education sector users are able to log in to any business application protected by
ESAA2 using the same set of “credentials” (ESAA2 user ID and password).

This Software Development Kit (SDK) document provides installation and configurat
ion information
for the authentication sub
-
system. Specifically, it describes the installation and configuration 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 associated SDKs are available for a number of platforms. This SDK describes the SP
for the
PHP

platform.

1.2

Target Audience


The audience for this document i
s:



Developers integrating education sector business applications with ESAA2.


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












ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page
7

of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro


2

Connection Process

2.1

Contact Details

The MoE
Sector Serv
ice Desk

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







ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page
8

of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro



2.2

Installation Prerequisites

The pre
-
requisites to install the
PHP
Service Provider for ESAA2

are:



Windows Server 2008R2

(
or
Windows 7 Professional for development)



Webserver (IIS

7.0

in this

case)



PHP

5.2

on the server
(
use PHP binaries for windows from downloaded folder

)



IDP (OpenAM server in this case)



OpenSSL for windows



A test environment that is accessible from

the

internet and has access to
the
internet
.







ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page
9

of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro





2.3

Installation Procedure

2.3.1

Pr
e
-
installation 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

Downlo
ad

the template war file:

esaa2
-
php
-
sp
-
template.zip
.

2.3.3

Configure and i
nstall the
template

application

Extract the
esaa2
-
php
-
sp
-
template.zip

to

a
target
folder

Go to Internet Information Services (IIS

7
.0
) manager and configure the self signed secure site
















ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro



Select your webserver on left side of the window, right click and select "Add Website"





Enter a SiteName for your site and select the folder where you have extracted "SimpleSAMLphp"







ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro




Now click on the name of the server in the Connections
column on the left. Double
-
click on
Server
Certificates
.





In the Actions column on the right, click on
Create Self
-
Signed Certificate...







ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro




Enter any friendly name and then click
OK
.





You will now have an IIS Self Signed Certificate valid for 1 y
ear listed under Server Certificates. The
certificate common name (Issued To) is the server name. Now we just need to bind the Self signed
certificate to the IIS site.


In the Connections column on the left, expand the sites folder and click on the websit
e that you want
to bind the certificate to. Click on
Bindings...

in the right column.







ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro







Click on the
Add...

button.





Change the Type to
https

and then select the SSL certificate that you just installed. Click
OK
.







ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro





You will now see the bindi
ng for port 443 listed. Click
Close
.








2.3.4

Configuring the SP



Generate a certificate
, e.g. using openssl

(install it from downloaded folder)
:



generateCert.cmd
:

del /f server.crt

del /f server.key

openssl req
-
new
-
x509
-
nodes
-
out server.crt
-
keyout

server.key
-
days 3650
-
config openssl.cnf



Once the certificate files are created. Place those files in "
cert"

folder under your hosted
SimpleSAMLphp application





Edit
config/config.php

and set the following values








ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro


/**


* Setup the following paramet
ers to match the directory of your installation.


* See the user manual for more details.


*/

'baseurlpath' => '
www
/',
//Change this folder to www

'certdir' => 'cert/',

'loggingdir'

=> 'log/',

'datadir' => 'data/',





/**


* This password must be kept secret, and modified from the default value 123.


* This password will give access to the installation page of simpleSAMLphp with


* metadata listing and diagnostic
s pages.


*/

'auth.adminpassword'

=> '
admin123
',

// Change admin password

'admin.protectindexpage'

=> false,

'admin.protectmetadata'

=> false,





/*


* Some information about the technical persons runnin
g this installation.


* The email address will be used as the recipient address for error reports, and


* also as the technical contact in generated metadata.


*/

'technicalcontact_name' => '
Technical Contact Name
',
// Change technical contact de
tails

'technicalcontact_email' =>
'tech@hyro.com
',





/*


* Enable


*


* Which functionality in simpleSAMLphp do you want to enable. Normally you would enable only


* one of the functionalities below, but in some cases you could run multiple function
alities.


* In example when you are setting up a federation bridge.


*/

'enable.saml20
-
idp'

=> false,

'enable.saml20
-
sp'

=> true,

//Add this configuration for Service Provider and
set it to True

'enable.shib13
-
idp'

=> false,

'enable.adfs
-
idp'

=> false,

'enable.wsfed
-
sp'

=> false,

'enable.authmemcookie' => false,





/*


* Should signing of generated metadata be enabled by default.


*


* Metadata signing c
an also be enabled for a individual SP or IdP by setting the






ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro



* same option in the metadata for the SP or IdP.


*/

'metadata.sign.enable' => TRUE,


// Set the value to TRUE in
-
case it is false



/*


* The default key & certificate which should
be used to sign generated metadata. These


* are files stored in the cert dir.


* These values can be overridden by the options with the same names in the SP or


* IdP metadata.


*


* If these aren't specified here or in the metadata for the SP or IdP, the
n


* the 'certificate' and 'privatekey' option in the metadata will be used.


* if those aren't set, signing of metadata will fail.


*/

'metadata.sign.privatekey' => 'server.key', //
Set the private key and certificate values to
the name of key

and certificate you have generated earlier

'metadata.sign.privatekey_pass' => NULL,

'metadata.sign.certificate' => 'server.crt',




Once set up you should be able to go to:

https://
YourWebserver
/www/module.php/saml/sp/metadata.php/default
-
sp



The above URL will provide

your SP metadata.



In OpenAM click
Register Remote Identity Provider
. Enter the URL above in the box for the
metadata URL in OpenSSO. Select the circle of t
rust to add this to. Click configure.





Then edit your
config
\
authsources.php

file, and add references to your certificates, IDP entity
and SP entity:



// An authentication source which can authenticate against both SAML 2.0

'default
-
sp' => array(

'sam
l:SP',



// The entity ID of this SP.

// Can be NULL/unset, in which case an entity ID is generated based on the metadata URL.

'entityID' => '
https://
YourWebServer
/www/module
.php/saml/sp/metadata.php/default
-
sp
',
// This is a path to your SP metadata URL



// The entity ID of the IdP this should SP should contact.

// Can be NULL/unset, in which case the user will be shown a list of available IdP
s.

'idp' => '
https://
OpenAMWebserver
/openam
',

// This is a path to your entity ID of IDP



// The URL to the dis
covery service.

// Can be NULL/unset, in which case a builtin discovery service will be used.

'discoURL' => NULL,






ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro


'certificate' => 'server.crt',


// Set the private key and certificate values

'privatekey' => 'server.key',

'redirect.sign' => TRUE,

'redirect.validate' => TRUE,

),



Edit
metadata
\
saml20
-
sp
-
hosted.php

and set it as follows



$metadata = array(


/*



* Example of a hosted SP


*/


'__DYNAMIC:1__' => array(


'host' => '__DEFAULT__',

'certificate' => 'server.crt',

'privatekey' => 'server.key',

'redirect.sign' => TRUE,

'redirect.validate' => TRUE,




)

);






ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro



2.3.5

Adding IDPs to SP

The service provider you are configuring needs to know about the identity providers you are going to
connect to it. This is configured by metadata stored in
metadata/saml20
-
idp
-
remote.php




Next go to:

http://YourOpenAMWebserver/opensso/saml2/jsp/exportmetadata.jsp

And copy that XML. Head to:

http://YourWebServer/www/admin/metadata
-
converter.php

And paste the Ope
nSSO IDP metadata into that box and click
Parse
.






Take the result and copy into:

<simpleSAMLphp>
\
metadata
\
saml20
-
idp
-
remote.php








ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro








The following table lists the supplied attributes form ESAA2

Table
1

-

Default ESAA2 SAML2

Attributes

Standard SAML2 Attribute Name

Description

ESAA2_UUID

Universally Unique ID


a unique opaque identifier defined by ESAA2

ESAA2_UID

User ID

ESAA2_GIVENNAME

First Name

ESAA2_SURNAME

Surname

ESAA2_SECURITYROLES

Security roles/entitlements for

the specific application


2.3.6

Test your application single
-
sign
-
on

Open the browser to your application URL, e.g.:

https://
yourWebServer
/www/

and goto
Authentication

tab









ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro




Click
Test configured authentication sou
rces











ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro





Click
Default
-
sp
and it will redirect you to the trusted IDP











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
















ESAA2


SA䵌M PHP SP Instal污l楯i 䝵楤i

Page


of


Last Updated:
5/11/2013 4:29 AM



Copyr楧it 2012 Hyro



On successfull authentication you will be redirected back to the SP authentication
page





2.4

Troubleshooting

The
PHP
SP installation was tested in
IIS

7
.0

and
PHP 5.2.17
.

Lowever version of PHP may

have
issues with
extensions and parsing of metadata
.