Detailed Description

Single Sign-On using SAML

Overview

This is an Assertion Consumer Service provided for web based ECE users to login to business partition (partition 1) of the application using Single Sign-On (SSO). The application supports both Identity provider (IdP) initiated SSO and Service provider (SP) initiated SSO. Only SAML 2.0 protocol is supported. To use this service:

Agent Single Sign-On Configuration must be configured by the administrator. Refer to "Agent Single Sign-On" section in "Administrator`s Guide to Administration Console" for more information.
A valid URL must be provided in the partition level setting Web server URL or Load Balancer URL in the Administration console.

Once the login is successful, ECE users can access Interaction APIs using the session token returned through a short lived cookie in the response.

Since: 12.0

APIs

Method	URL	Description
POST	`/SAML/SSO/POST.controller`	Authenticates and logs in ECE users using SSO.

Permissions

Licenses

The user must have at least one of the User Licenses assigned. As the result of successful user login, all assigned user licenses are consumed according to ECE rules of license consumption. See the "About Users, Groups, Roles, and Actions" section in "Administrator`s Guide to Administration Console" for more information on ECE licenses.

Request

Request Body

The request must contain the following request parameter (either in a web form or as a query parameter):

SAMLResponse: This parameter must contain a Base64 encoded SAML assertion. SAML assertion may optionally contain the following:
1. application_url: A SAML attribute that contains an absolute URL to which the user will be redirected upon successfully logging in. Additionally, this URL may optionally contain the following query parameters:
  - application_type (may also be provided through other means. See application_type under Supported request parameters for more info.)
  - forceLogin (may also be provided through other means. See forceLogin under Supported request parameters for more info.)
  - acceptLanguage (may also be provided through other means. See acceptLanguage under Supported request parameters for more info.)
2. application_type: A SAML attribute that indicates the application or module to which the user wants to login. Only WS API for ECE user is currently supported, and hence, this attribute value must be 'API'.
3. forceLogin: A SAML attribute that allows to forcefully log in a user when they already have 5 concurrent web service sessions active. See forceLogin under Supported request parameters for more info.
4. acceptLanguage: A SAML attribute that contains the language locale accepted by client. See acceptLanguage under Supported request parameters for more info.
5. peripheralName: (only required for integrated user) A SAML attribute that contains the Name of the peripheral to which this integrated user belongs. Must be a valid peripheral name for UCCE configuration. Must not exceed 124 characters.

Request Body XML schemas

SAMLResponse request parameter must use the following SAML 2.0 assertion schema:

https://docs.oasis-open.org/security/saml/v2.0/saml-schema-assertion-2.0.xsd

Supported request parameters

Following optional parameters are allowed for all application types in the request. These parameters can be sent as form or query parameters.

Name	Description	Allowed values	Default value
RelayState	This parameter must contain an absolute URL where the user will be redirected to after a successful login. Note that this will take precedence over application_url provided through SAML assertion. Additionally, this URL may optionally contain the following query parameters: application_type (see application_type in this table below for more info) forceLogin (see forceLogin in this table below for more info) acceptLanguage (see acceptLanguage in this table below for more info) Example of RelayState: https://www.example.com?application_type=API&forceLogin=yes&acceptLanguage=es-ES	`N/A`	`N/A`
application_type	This need not be provided, if already provided through other means, e.g. RelayState, SAML assertion, etc. This parameter indicates the application or module to which the user wants to login. Only WS API for ECE users is currently supported and hence, the parameter value must be 'API'.	API	`N/A`
forceLogin	This need not be provided, if already provided through other means, e.g. RelayState, SAML assertion, etc. In the application, a maximum of 5 concurrent web service sessions are allowed for a user. The sixth request will fail, unless this parameter is sent along with the request. If this parameter is sent by the client, the oldest session (based on session creation time) is terminated and a new session is created.	yes	`N/A`
acceptLanguage	This need not be provided, if already provided through other means, e.g. RelayState, SAML assertion, etc. This parameter must contain the language locale accepted by client (used for locale specific error responses).	Supported 'Accept-Language' header codes	default system language
peripheralName (only required for integrated user)	Name of the peripheral to which this integrated user belongs. Must be a valid peripheral name for UCCE configuration. Must not exceed 124 characters.	`N/A`	`N/A`

Required parameters

One of RelayState request parameter or application_url SAML attribute is required. This is because Assertion Consumer Service needs to know where to redirect the client after successful authentication. RelayState takes precedence over application_url, so if both are provided, application_url will be ignored.
application_type parameter is required. As stated above it can be provided through multiple channels, namely through RelayState request parameter, application_url SAML attribute, its own request parameter, or as a SAML attribute. If provided through more than one channel, application_type will be determined in the following order of precedence:
1. If RelayState parameter is sent in the request and it contains application_type query parameter, this value will be used.
2. Only if RelayState parameter is not sent in the request, then application_url SAML attribute will be checked for presence of application_type query parameter. If present, this value will be used.
3. SAML attribute called application_type included in SAMLResponse request parameter.
4. Request parameter called application_type sent with HTTP request to this service.

Notes:

The order of precedence for determining forceLogin and acceptLanguage parameters is exactly the same as the order for application_type parameter. Namely, 1) RelayState, 2) application_url (when RelayState is absent), 3) SAML attribute, 4) request parameter.
Unrecognized request parameters are ignored.

Response

If login is successful:

The user will be redirected (response code 302) to a URL chosen by client. This URL will be determined in the following order of precedence:
- RelayState parameter: If RelayState parameter is sent in the request, it will be used as the redirection URL.
- SAML assertion attribute: If RelayState parameter is not sent and application_url SAML attribute is present in the SAML assertion sent in the request, the value of this SAML attribute will be used as the redirection URL.
Note: If redirection URL is not sent in at least one of the above mentioned parameters, the user will be redirected to the error page.
As part of the response, a short lived cookie (alive for 2 minutes) named egain_sso_session will be set by the application. This cookie will contain the session token generated for the user. This token must be stored by the client and sent as a header in all subsequent Interaction API calls.

If login is not successful:

The user will be redirected (response code 302) to a standard error page. This error page will display an error code and a user friendly error description localized in the language sent in acceptLanguage parameter. If acceptLanguage parameter is not sent in the request, error description will be returned in the default system language.

Errors

Below are a few scenarios in which the application will error out:

Required request parameter is missing.
Unsupported request parameter value is sent in the request.
The user is not found and SAML attributes required to create a new user are not present in the SAML assertion.
Unsupported SAML attribute value is sent in the SAML assertion.
The user cannot be uniquely identified with the provided subject or SAML attribute in SAML assertion or is not a department user.
Element values sent in the SAML assertion do not match the corresponding Agent SSO configuration values in admin console.
Invalid certificate found in SAML assertion.
SAML assertion is expired.
SAML assertion is not Base64 encoded.
Invalid SAML entity is sent in the SAML assertion.
Subject value is empty in the SAML assertion.
The user identified by the SAML assertion, currently has 5 active web service sessions and forceLogin parameter with value yes is not sent in the request.
Invalid value of acceptLanguage or forceLogin parameter is provided.
There was an error during processing.

Unauthenticated Response from APIs

If SP initiated Single Sign-On is enabled, and a request made to any of the APIs results in a 401 response code (due to 'X-egain-session request header is missing' or 'invalid or expired session'), the response will contain providers element in addition to code and developerMessage. This information can be used to initiate the login process on the Identity Provider (IdP).

Below is a sample 401 error response from REST APIs when SP initiated Single Sign-On is enabled:

XML response

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<error xmlns="http://bindings.egain.com/ws/model/v15/gen/common">
    <code>401-101</code>
    <developerMessage>Invalid or expired 'X-egain-session' header provided. New login is required.</developerMessage>
    <providers>
        <provider>
            <idp>
                <idpLoginURL>https://idp_server1.com/login</idpLoginURL>
                <samlRequest>PD94bWwgdmVyc2lvbj0iMS4wIiBlbmN...</samlRequest>
            </idp>
            <default>true</default>
        </provider>
    </providers>
</error>

JSON response

{
    "code": "401-101",
    "developerMessage": "Invalid or expired 'X-egain-session' header provided. New login is required.",
    "providers": {
        "provider": [
        {
            "idp": {
                "idpLoginURL": "https://idp_server1.com/login",
                "samlRequest": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmN..."
            },
            default": true
         }]
    }
}