Detailed Description

Single Sign-On using SAML bearer token

Overview

This is an authentication API, which can be used by the customers to login using Single Sign-On (SSO) to access Interaction APIs and Access APIs. This API supports logging in using a SAML2 bearer token using OAuth2. To use this API for customer login, Customer Single Sign-On Configuration must be configured by the administrator. Refer to "Customer Single Sign-On" section in "Administrator`s Guide to Administration Console" for more information.

Upon successful verification of the SAML assertion, this API will generate a session ID which will be returned as a header. This session ID can be used by the customers to access Customer Portal APIs as well as Access APIs. Session ID, once expired, cannot be used again and a new session ID can be created by using this API.

As part of login using SSO, customer auto provisioning is also supported. With auto provisioning, customer attributes sent in SAML assertion will be used to create customers the first time they try to log in. If the customer exists, customer attributes sent in SAML assertion will be updated for the identified customer.

Since

15.0.2.1

APIs

Method	URL	Description
POST	`/ws/v15/context/authentication/user/sso/oauth2/token`	Authenticates customers logging into the application using SSO.

Permissions

Licenses

Following licenses will be consumed as part of this API. These must be installed and available for consumption:

ECE Selfservice + AI

Request

Request headers

Name	Description	Allowed values	Default value
Content-Type	Media type sent by the client.	application/x-www-form-urlencoded	N/A
Accept	Content type accepted by the client.	`application/xml` or `application/json`	N/A
Accept-Language	Language locale accepted by client (used for locale specific fields in resource representation and in error responses)	Supported 'Accept-Language' header codes	`default system language`

Request Body

The request body is mandatory. Request body must contain a single form with the following parameters:

grant_type: This form parameter must contain the type of grant sent in the request. Only supported value is "urn:ietf:params:oauth:grant-type:saml2-bearer".
assertion: This form parameter must contain a Base64 encoded SAML assertion. The customer identifier must be located in the NameID element of the subject statement of SAML assertion. SAML assertion may optionally contain customer attributes as SAML Attributes to create or modify a customer. If customer attributes are not provided, auto provisioning and modification to customer record will not happen as part of SSO.

Note: An attribute 'applicationType' can optionally be provided in SAML assertion. This indicates the application which the customer wants to login to. Only Secure Inbox is currently supported, and hence, its value must be 'secure_inbox'.

Creation of new customer during SSO login

If a customer is not found in the ECE application with the subject provided in the SAML assertion, the application will check whether mergeOnAttribute SAML attribute is provided. If provided, the application uses the field specified in mergeOnAttribute to search for a customer.

If a customer is found using mergeOnAttribute then this customer's information will be updated with all the customer attributes sent in the SAML Assertion and the customer identifier sent in the subject. If the customer is not found using subject and mergeOnAttribute both, a new customer is created in the application. The customer type will be individual.

Following customer attributes are required to be sent in the SAML attributes to create a new customer successfully:

Attribute Name	Description
department	Department name in which to lookup the customer. This must be provided only if the customer departmentalization setting is enabled in the application.
firstName	First name of the contact. Must not exceed 124 characters.

Following optional customer attributes are allowed in the SAML attributes to create a new customer:

Attribute Name	Description
middleName	Middle name of the contact. Must not exceed 124 characters.
lastName	Last name of the contact. Must not exceed 124 characters.
dateOfBirth	Must be a date in the past. Must be in XML date format (yyyy-mm-dd).
custom.<name>	Custom attributes of the contact: "<name>" is the internal name of the custom attribute. Name must match one of the custom attributes configured in application. If the custom attribute is configured as an enumeration, the value must be one of the predefined values. For string type of custom attribute that is not configured as an enumeration, refer list of Allowed Characters For Custom Attributes.
email.address	Email address of the contact. Refer Email Address definition for the valid email address format.
twitter.ID	Twitter ID of the contact. Must not exceed 255 characters.
facebook.ID	Facebook ID of the contact. Must not exceed 255 characters.
instagram.ID	Instagram ID of the contact. Must not exceed 255 characters.
appleOpaqueId.ID	Apple Opaque ID of the contact. Must not exceed 255 characters.
home.phone.countryCode	Country code of the home phone number of the contact. Must be a number not exceeding 9 digits.
home.phone.number	Home phone number of the contact. This accepts any string representation. It is the client's responsibility to send in the correct number. Must not exceed 25 characters.
mobile.phone.countryCode	Country code of the mobile phone number of the contact. Must be a number not exceeding 9 digits.
mobile.phone.number	Mobile phone number of the contact. This accepts any string representation. It is the client's responsibility to send in the correct number. Must not exceed 25 characters.
office.phone.countryCode	Country code of the office phone number of the contact. Must be a number not exceeding 9 digits.
office.phone.number	Office phone number of the contact. This accepts any string representation. It is the client's responsibility to send in the correct number. Must not exceed 25 characters.
externalId	A unique external ID for the contact person. If customer departmentalization is enabled in the application, this must be unique in the department of the customer. If customer departmentalization is not enabled, this must be unique in the application. Must be at least 1 character, and must not exceed 255 characters. Refer list of Allowed Characters.
mergeOnAttribute	Attribute on which existing customer records will be merged. Supported values are: email.address home.phone.number mobile.phone.number office.phone.number externalId custom.<name>

Modification of existing customer during SSO login

If a single customer is found in the ECE application with the subject provided or by using the mergeOnAttribute in the SAML assertion, the customer information is updated using the customer attributes in SAML attributes and the customer identifier sent in the subject.

Following optional customer attributes are allowed in the SAML Attributes to modify an existing customer:

Attribute Name	Description
department	Department name in which to lookup the customer. This must be provided only if the customer departmentalization setting is enabled in the application.
firstName	First name of the contact. Must not exceed 124 characters. Must be provided to create a new customer in the application.
middleName	Middle name of the contact. Must not exceed 124 characters.
lastName	Last name of the contact. Must not exceed 124 characters.
dateOfBirth	Must be a date in the past. Must be in XML date format (yyyy-mm-dd).
custom.<name>	Custom attributes of the contact: "<name>" is the internal name of the custom attribute. Name must match one of the custom attributes configured in application. If the custom attribute is configured as an enumeration, the value must be one of the predefined values. For string type of custom attribute that is not configured as an enumeration, refer list of Allowed Characters For Custom Attributes.
email.address	Email address of the contact. Refer Email Address definition for the valid email address format.
twitter.ID	Twitter ID of the contact. Must not exceed 255 characters.
facebook.ID	Facebook ID of the contact. Must not exceed 255 characters.
instagram.ID	Instagram ID of the contact. Must not exceed 255 characters.
appleOpaqueId.ID	Apple Opaque ID of the contact. Must not exceed 255 characters.
home.phone.countryCode	Country code of the home phone number of the contact. Must be a number not exceeding 9 digits.
home.phone.number	Home phone number of the contact. This accepts any string representation. It is the client's responsibility to send in the correct number. Must not exceed 25 characters.
mobile.phone.countryCode	Country code of the mobile phone number of the contact. Must be a number not exceeding 9 digits.
mobile.phone.number	Mobile phone number of the contact. This accepts any string representation. It is the client's responsibility to send in the correct number. Must not exceed 25 characters.
office.phone.countryCode	Country code of the office phone number of the contact. Must be a number not exceeding 9 digits.
office.phone.number	Office phone number of the contact. This accepts any string representation. It is the client's responsibility to send in the correct number. Must not exceed 25 characters.
externalId	A unique external ID for the contact person. If customer departmentalization is enabled in the application, this must be unique in the department of the customer. If customer departmentalization is not enabled, this must be unique in the application. Must not exceed 255 characters. Refer list of Allowed Characters.
mergeOnAttribute	Attribute on which existing customer records will be merged. Supported values are: email.address home.phone.number mobile.phone.number office.phone.number externalId custom.<name>

Supported API specific query parameters

Name	Description
forceLogin	This is an optional query parameter. The only possible value is "yes". In the application, a maximum of 5 concurrent sessions are allowed for a customer. 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.
providerId	This is an optional query parameter. If provided, this must contain the ID of the provider to be used for authenticating the request. If this parameter is not provided, default provider will be used for authenticating the request.

Supported common query parameters

None

Request body XML schemas:

The Base64 decoded assertion form parameter sent in the request body must conform to SAML 2.0 assertion schema. It is assumed that all mandatory SAML assertion elements required to successfully verify the SAML assertion will be sent in the request.

Response

Response will contain the following elements in case of success:

access_token: The value will be the new session identifier created for the customer.
token_type: The type of token returned in the response. The value will always be "Bearer".

Response will contain the following elements in case of error:

error: The values can be one of: invalid_request, unsupported_grant_type, invalid_grant, access_denied, and server_error.
error_description: Localized user friendly error message.

Response headers

Name	Description	Possible values
X-egain-session	Newly generated session ID	N/A
Content-Type	Media type of response body	`application/xml` or `application/json`

Response body XML schemas:

v15-schema-context-OAuthLoginResponse - used in case of success and error

HTTP status codes

Success Status codes

200 - OK

The customer was successfully authenticated. The new session identifier will be sent in the response body as well as in the "X-egain-session" response header.

Failure Status codes

400 - Bad Request, with error value "invalid_request"

Unsupported query or form parameter is sent in the request.
Unsupported query or form parameter value is sent in the request.
Request body does not contain the required form parameter.
Request body is empty.
If the customer is not found (based on subject or mergeOnAttribute) and SAML attributes required to create a new customer are not present in the SAML assertion.
Unsupported SAML attribute is sent in the SAML assertion.
Unsupported SAML attribute value is sent in the SAML assertion.
If the customer cannot be uniquely identified with the provided subject or mergeOnAttribute in the SAML assertion.
If duplicate email address is provided in the SAML assertion.

400 - Bad Request, with error value "unsupported_grant_type"

Unsupported value of "grant_type" form parameter is sent.

401 - Unauthorized with error as "invalid_grant"

Unsupported element is sent in the SAML assertion.
Element values sent in the SAML assertion do not match the corresponding Customer 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.

403 - Forbidden with error as "access_denied"

If the customer identified by the SAML assertion provided in request body, currently has 5 active web service sessions and forceLogin query parameter with value "yes" is not sent in the request.
If the customer identified by the SAML assertion provided in request body is a system created or anonymous customer.

406 - Not Acceptable, with error as "invalid_request"

Invalid value of Accept-Language header.

500 - Internal server error, with error as "server_error"

Examples:

Example 1 - Login an existing customer using SSO
Example 2 - Login a new customer with supported query parameters
Example 3 - Login an existing customer using SSO with customer updation