Web Components SSO Guide
Overview of Web Components SSO Process
Single sign-on (SSO) is an authentication method that allows users to log in with a single set of credentials to any related yet independent software systems.
upSWOT uses SSO technology to provide users secure access to embedded Web Components through a single sign-on to their User Platform (such as online banking or any other web application where the Web Components are embedded) without re-entering authentication factors.
The diagram below describes a Single Sign-On process for upSWOT Web Components
Step 1. When a user logs in to their User Platform, an authorization request is sent to the application server of that organization.
Step 2. The server checks whether this user belongs to the pool of authorized clients of this organization. If yes, the server responds that the authorization was successful.
Step 3. Once the Web Component is launched in the User Platform, it sends a GetToken request with the obtained user authorization data to the upSWOT application server.
https://{host}/{tenant}/api/AuthService/GetToken?authProps1=…&authPropsN=…
Where:
authProps is a user authorization parameter (JWT token, session ID, etc.) received from the User Platform in the auth property of the Web Component (see Web Components Integration Manual for more details).
Note
The structure and content of the user authorization data may vary depending on the hosting (banking) app. However, the upSWOT server is able to process any authorization parameters passed in the GET /GetToken request. For security considerations, it is recommended to use certain dynamic parameters that would uniquely identify the user while also ensuring the authenticity of the request, such as an authentication token, session ID, etc. Email may be used additionally (it is not required) but should not be the only parameter.
Step 4. To confirm if the user is an authorized client, the upSWOT server sends a POST request to the User Platofrm’s application server. The request body contains an array of unaltered user authorization data received in the previous step.
{
"authProps1":"...",
"authPropsN":"..."
}
The hosting organization (i.e. the owner of the User Platform) is expected to implement a web service to receive and process such requests. The URL of this web service is specified in the tenant's system settings. And, if the request is proxied, the proxy server parameters must also be defined in these settings:
user:password@http://your-proxy-ip-address:port
Step 5. After verifying the user authorization parameters, the User Platofrm’s application server responds to the upSWOT request with user and company data in JSON format (see Expected JSON Structure Example). If user verification fails, the server returns a response status code of 401 Unauthorized.
Step 6. The upSWOT app server checks if the user and company exist in the database:
- If no, new user and company entities are created in the upSWOT database with the received parameters.
- If yes, the user and company entities in the upSWOT database are updated with the received parameters to reflect any changes made by the user in their banking app.
After that, the upSWOT server generates a JWT token and sends it back to the Web Component. The Web Component will now use this token to communicate with the upSWOT app server.
In some cases, instead of generating a JWT token, the upSWOT server may receive it directly from the User Platofrm’s application server via the inter-server requests. The JWT token is then stored in the token property of the Web Component.
When the user logs in to the upSWOT solution via SSO, the Privacy Policy is accepted automatically, and the Privacy Policy block is hidden from all Web Components. This feature is enabled by default, but it can be changed through tenant system settings.
Expected JSON Structure Example (Step 5)
{
"name": "John Doe",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"externalId": "123456",
"isActive": true,
"language": "en-US",
"accountData": [
{
"type": 0,
"name": "Acme Corporation",
"mobilePhone": "+1 334-123-4567",
"email": "[email protected]",
"alpha3Code": "USA",
"externalId": "7890",
"isActiveCompany": true,
"identifier": [
{
"value": "123-45-6789",
"type": "SSN"
}
],
"companyIndustry": "Oilseed and Grain Combination Farming",
"annualRevenue": "500,000",
"numberOfBusinessLocations": "1",
"numberOfEmployees": "20",
"address": {
"street": "13785 Research Blvd",
"streetNumber": "Suite 150",
"city": "Montgomery",
"state": "AL",
"zip": "10000",
"addressType": "1",
"countryIsoCode": 840
},
"phones": [
{
"countryCode": 840,
"cityOrAreaCode": 334,
"localNumber": 1234567,
"phoneTypeName": "1"
}
]
}
],
"additionalData": {
"favoriteColor": "blue",
"favoriteFood": "pizza"
}
}
Parameters Description
NAME | TYPE | DESCRIPTION |
---|---|---|
name | String | Full name of the user. |
firstName | String | First name of the user. |
lastName | String | Last name of the user. |
email* | String | Email address of the user. *Required parameter. |
externalId | String | Unique identifier of the user in the banking system. |
isActive | Boolean | True if the user is active in the banking system and should be active in the upSWOT system. False otherwise. Note: If omitted, this parameter will default to false. |
language | String | Code of the user’s localization language in the banking system. Expected format: en-US . |
accountData | Array | Companies or other legal entities related to the user. It may also contain related addresses and phone numbers. |
accountData.type | Integer | Type of the user’s company. The recommended value is 0. |
accountData.name | String | Name of the user’s company. |
accountData.mobilePhone | String | Cell phone number of the user’s company. |
accountData.email | String | Email address of the user’s company. |
accountData.alpha3Code | String | Three-letter country code of the user’s company. |
accountData.externalId | String | Unique identifier of the user’s company in the banking system. |
accountData.isActiveCompany | Boolean | Defines whether the company is active and its data is displayed in Web Components. Relevant if the user has more than one company. True if the data about this company is displayed in Web Components. False otherwise. |
accountData.identifier | Array | Parameters that uniquely identify the user’s company. |
accountData.identifier.value | String | Value of the parameter that uniquely identifies the user’s company. For example, SSN. |
accountData.identifier.type | String | Type of the parameter that uniquely identifies the user’s company. It can be: SSN – Social Security Number EIN – Employer Identification Number ITIN – Tax processing number for individuals who are not eligible for an SSN. Note: please contact upSWOT if other identifier types will need to be configured in the system, including for countries other than the U.S. |
accountData.companyIndustry | String | Title of the company’s industrial sector according to the North American Industry Classification System (NAICS). Any aggregation level can be provided. Note: please contact upSWOT if other industry classifications will need to be configured in the system, including for countries other than the U.S. |
accountData.annualRevenue | String | Company’s annual revenue. |
accountData.numberOfBusinessLocations | String | Number of the company’s locations. |
accountData.numberOfEmployees | String | Number of the company’s employees. |
accountData.address | String | Company’s address. |
accountData.address.street | String | Company’s building number and street name. |
accountData.address.streetNumber | String | Company’s apartment number. |
accountData.address.city | String | City where the company is registered. |
accountData.address.state | String | State where the company is registered. |
accountData.address.zip | String | Zip or postal code. |
accountData.address.addressType | String | Type of the company’s address. It can be: 1 – Business 2 – Home 3 – Other 4 – Bill Payee |
accountData.address.countryIsoCode | Integer | Numeric code of the country according to ISO 3166. |
accountData.phones | Array | Company’s phone number(s). |
accountData.phones.countryCode | Integer | Numeric code of the country according to ISO 3166. |
accountData.phones.cityOrAreaCode | Integer | City or area code for the company’s phone number. |
accountData.phones.localNumber | Integer | Company’s phone number. |
accountData.phones.phoneTypeName | String | Type of the company’s phone number. It can be: 1 – Business 2 – Car 3 – Home 4 – Mobile 5 – Pager 6 – TDD 7 – Other 8 – Fax |
additionalData | Object | Additional parameters related to the user. |
Note
From the technical point of view, the only required field is email, though it is strongly recommended to pass the following fields via SSO as well:
isActive
(omitting this parameter will cause the user to be deactivated in the upSWOT system by default)externalId
name
accountData.name
accountData.email
accountData.externalId
Updated about 2 months ago