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.



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).



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.


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:


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

nameStringFull name of the user.
firstNameStringFirst name of the user.
lastNameStringLast name of the user.
email*StringEmail address of the user. *Required parameter.
externalIdStringUnique identifier of the user in the banking system.
isActiveBooleanTrue 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.
languageStringCode of the user’s localization language in the banking system. Expected format: en-US.
accountDataArrayCompanies or other legal entities related to the user. It may also contain related addresses and phone numbers.
accountData.typeIntegerType of the user’s company. The recommended value is 0.
accountData.nameStringName of the user’s company.
accountData.mobilePhoneStringCell phone number of the user’s company.
accountData.emailStringEmail address of the user’s company.
accountData.alpha3CodeStringThree-letter country code of the user’s company.
accountData.externalIdStringUnique identifier of the user’s company in the banking system.
accountData.isActiveCompanyBooleanDefines 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.identifierArrayParameters that uniquely identify the user’s company.
accountData.identifier.valueStringValue of the parameter that uniquely identifies the user’s company. For example, SSN.
accountData.identifier.typeStringType 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.companyIndustryStringTitle 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.annualRevenueStringCompany’s annual revenue.
accountData.numberOfBusinessLocationsStringNumber of the company’s locations.
accountData.numberOfEmployeesStringNumber of the company’s employees.
accountData.addressStringCompany’s address.
accountData.address.streetStringCompany’s building number and street name.
accountData.address.streetNumberStringCompany’s apartment number.
accountData.address.cityStringCity where the company is registered.
accountData.address.stateStringState where the company is registered.
accountData.address.zipStringZip or postal code.
accountData.address.addressTypeStringType of the company’s address. It can be:
1 – Business
2 – Home
3 – Other
4 – Bill Payee
accountData.address.countryIsoCodeIntegerNumeric code of the country according to ISO 3166.
accountData.phonesArrayCompany’s phone number(s).
accountData.phones.countryCodeIntegerNumeric code of the country according to ISO 3166.
accountData.phones.cityOrAreaCodeIntegerCity or area code for the company’s phone number.
accountData.phones.localNumberIntegerCompany’s phone number.
accountData.phones.phoneTypeNameStringType 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
additionalDataObjectAdditional parameters related to the user.



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