... h2. SAML 2
h3. 1. Introduction
Security Assertion Markup Language (SAML) is an XML-based open standard for exchanging authentication and authorization data between security domains.
lams_saml project has been originally created for World Vision (WVI) Single Sign On (SSO) purposes. An user logging into WVI Central portal gains access to LAMS as well.
lams_saml is not limited to cooperation with WVI.It offers a more generic approach and with proper configuration, it can be used to process authentication assertions from other Identity Providers (IdP).
h3. 2. Installation
Installation of lams_saml project consists of:
\- setting necessary properties in lams_saml configuration file
\- deploying the project, which also enables SamlServlet in LAMS EAR configuration files
\- as System Administrator, configuring an integrated server
\- optionally, setting up certificates for SSL access to LAMS and for IdP signature validation
Explanation of installation steps is available in readme.txt file in lams_saml project directory.
h3. 3. Accessing LAMS
Access to LAMS through SAML starts with a call to "/saml/access" context.
There are two required parameters:
* idp; Identity Provider name for which LAMS reads a mapped URL from configuration file.
This URL should lead to login page of IdP which sends assertion back to LAMS after successful authentication.
Request will fail if user is not authenticated in LAMS (his data is not stored in session) and this parameter is missing.
* group; course ID which user should be assigned to in LAMS.
This is a required parameter.
An example URL is: [http://mylamsserver.com/lams/saml/access?idp=wvi&group=SomeGroup|http://mylamsserver.com/lams/SamlServlet]
h3. 4. Assertion processing
IdentityProvider sends authentication assertion to LAMS Assertion Consumer (AC) using POST method.
GET method is not available and will result in error.
|
AC is available at "/saml/authenticate" context. An example URL is: [http://mylamsserver.com/lams/saml/authenticate|http://mylamsserver.com/lams/SamlServlet]
|
[|http://mylamsserver.com/lams/SamlServlet]
|
Project's main SamlServlet class processes an authentication assertion following these steps:
|
...
# Check if connection is secure (SSL), otherwise result in an error page sent to user.
By default the connection is not required to be secure (behaviour configurable in lams_saml config file).
# Extract SAML assertion from HTTP request and log its contents on DEBUG level.
# Check if the assertion issuer is in valid issuer list, otherwise result in an error page.
The list is configurable.
# Validate the issuer signature using its certificate.
By default validation is performed but if it fails, it will not result in an error page (behaviour configurable).
How to set up issuer certificate is explained in lams_saml installation manual.
# Validate assertion conditions.
Assertion processing start time is validated against "notBefore" and "notOnOrAfter" conditions.
By default validation is performed and if it fails, it will result in an error page (behaviour configurable).
# Extract NameID and check if the user exists in LAMS.
If user exists, he is logged into LAMS by sending an internal request to LoginRequestServlet with proper parameters.
If he does not exist, he is registered and then logged into LAMS, both tasks accomplished by a single internal call to LoginRequestServlet.
To register an user, the following authentication assertion attributes need to be present:
* first name; the attribute name must be "givenName" or OID notation can be used; OID for this parameter is 2.5.4.42, so the accepted attribute name is "urn:oid:2.5.4.42"
* last name; attribute name either "surname" or OID 2.5.4.4
* email; attribute name either "mail" or OID 0.9.2342.19200300.100.1.3
if email attribute is not found or its value is not in valid format,
user NameID is checked - if it is in "emailAddress" format, the value is used as the user email
|
* group; attribute name "group", no OID available; it is course ID which user should be assigned to in LAMS;
optional - it should have been provided in previous call to "access" context
|
* office; attribute name "group", no OID available; it is regional office which user should be assigned to in LAMS; optional
|
* office; attribute name "office" or OID 1.3.6.1.4.1.5923.1.1.1.5
optional - it is regional office which user should be assigned to in LAMS
|
If first or last name is missing, user will not be registered and will receive an error page.
|
...
Successful assertion processing results in the user being authenticated and redirected to LAMS home page.
|