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

📘

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