6.2. SSO Setup

Home Prev	EasyAccess 4.3 Getting Started Guide	Next

This section describes how to set up a Single Sign On (SSO) capability in EasyAccess. SSO is a special type of federation scenario. The initial authentication of a user is the same as for a normal federation scenario wih a single service provider. However, the user can then change to a another service provider (often within the same organization) within the same browser session, without having to authenticate again.

The sequence of processing steps for SSO is the same as those described at the beginning of Section 6.1, Basic Federation Scenario Setup for a standard federation scenario with a single service provider. However, the following additional steps will occur when the user tries to access additional service providers during the same browser session.

The new service provider redirects the browser back to EasyAccess for authentication.
The browser's old SAML assertion for the first service provider tells EasyAccess that the user has already been authenticated so EasyAccess provides a new SAML assertion to the browser for the new service provider without further authentication.
The browser is redirected back to the new service provider with the new SAML assertion.
The service provider accepts the SAML assertion and allows access.

The detailed setup steps for SSO are the following:

A. Set up a Federation Scenario

Set up a federation scenario as normal. Doing this is described in Section 6.1, Basic Federation Scenario Setup. The scenario could use simple username and password authentication or could use one of the multi-factor authentication options.

Note that, instead of the metadata for just a single service provider being uploaded to EasyAccess in the scenario, the metadata for all the potential service providers should be uploaded.

B. Modify the Scenario's Execution Flow

Changes are required to the valves in the scenario's execution flow. The list of valves that will be required in this particular example are the following and in the following order:

LockoutCheckValve
InputParameterExistValidatorValve
LDAPSearchValve
LDAPBindValve
AuthnRequestDecoder
AssertionProvider (one for each service provider)

The above valves will now be described in detail:

The default LockoutCheckValve should be left as it is. This checks if the user is locked out for any reason such as too many authentication attempts. This valve could be left out while testing the setup but should be included in a production environment.
The default InputParameterExistValidatorValve can also be left as it is. This checks that the user has entered a password.
The LDAPSearchValve is needed to retrieve the user's data based on username. The attributes property specifies which user data will be available to subsequent valves. This property may need to be changed to include data required in the SAML assertion sent to particular service providers. Below is a JSON example which shows some typical values.
```
{
  "name": "LDAPSearchValve",
  "enabled": "true",
  "config": {
    "connection_ref": "bbd7198c-0a6c-43aa-b62b-cd7552c8b4cf",
    "base_dn": "DC=maso,DC=lan",
    "scope": "SUB",
    "size_limit": "0",
    "filter_template": "samAccountName={{request.username}}",
    "attributes": "objectGUID,samAccountName,sn,mail,givenName",
    "binary_attrs": "objectGUID"
  }
},
```
Note that the connection_ref value is automatically set when the connection is selected during scenario creation in the WebUI.
The default LDAPBindValve can be left as it is. This authenticates the entered password against the stored LDAP value.
Insert an AuthnRequestDecoder. This must be included before multiple AssertionProvider instances (which is the case with SSO) when each instance is testing the issuer property. This valve needs no customization and its default values are listed below.
```
{
  "name": "AuthnRequestDecoder",
  "enabled": "true",
  "config": {
    "proceed_on_error": "false"
   }
 },
```
Ensure there is an AssertionProvider valve for each service provider so that the required values for the additionalAttributes property are specified for the SAML assertion created. The following AssertionProvider example would only be used if the service provider name is MyExampleSP.
```
{
  "name": "AssertionProvider",
  "enabled": "true",
  "config": {
    "targetEntityID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
    "nameIDAttribute": "sAMAccountName",
    "additionalAttributes": "userid,mail,givenName",
    "exec_if_expr": "flow.property('issuer').equals('MyExampleSP')"
  }
},
```
Note that the targetEntityValue for all assertions must be the same ID value of the scenario identity provider. Also note that the additionalAttributes can include any items in the list specified in the attributes property of the LDAPSearchValve specified earlier.

Some service providers may require specific user data be included in the SAML assertion with specific property names. Customizing SAML data is discussed further Section 6.4, Customizing SAML Assertions.

C. Configure the SAML Metadata on the Service Provider

The SAML IdP Metadata for this scenario must be configured on the service provider. The metadata can be configured either in a file or as a URL on the EasyAccess server. This is described further in Section 6.1, Basic Federation Scenario Setup.

D. Set Up EasyAccess Redirection Without Authentication

When a user tries to connect to another service provider after being initially authenticated for the first provider, EasyAccess must be set up so it does not ask the user to authenticate again. Instead, EasyAccess will read the old SAML assertion from the browser and give the browser a new assertion before redirecting it back to the requesting service provider. Setting up this redirection in Easy Access requires the creation of a second, secondary federation scenario and doing this is described in Section 6.3, Redirecting SAML Requests.