Single Sign-On (SSO)

Single Sign-On (SSO) is a feature that can be added to WTS sites and be used as an authentication method. We support SAML 2.0 Identity Providers. Existing sites adding on SSO will need to migrate to the SSO server.  A custom subdomain will be provided or if a dedicated server was purchased a custom domain is already provided.

SSO Setup

To fully configure SSO, at a minimum, the following is required:

• Your customers IT team will need to configure their SSO IDP (Identity Provider) for this metadata

• We will need your team to provide: 

  • The URL of the customers IDP server's metadata or a copy of the file

  • The details for what attribute the customer will be releasing to us for authentication (Namespace/Nameformat is important)

  • Test credentials for the customers IDP server

  • If Test credentials cannot be provided then we will request a SAML Trace once we are ready to proceed with testing.

After all required information is provided the SSO setup will begin and support will update you to let your team know if more information is required or if we are ready to proceed to the testing phase.

Testing

Once all information is exchanged and configured we will move into the testing phase. 

• At this point, the subdomain should be redirecting you to the customers SSO login page. 

• Metadata was exchanged and the customers IT configured their SSO IDP for the metadata provided.

• An attribute was defined but further testing may be needed to confirm no additional configuration settings need to be made for this attribute.

• If a test user is provided, testing will be completed with this user to confirm authentication is working

• If no test user is provided we will require your team or the customer to capture a SAML Trace while attempting to authenticate using a user in the WTS system. This will require you to add the SSO ID (attribute being released) to a User in the system. The user with an SSO ID added will need to be used when attempting to log in. At this stage, this may not be successful and that is ok. The purpose of this test is only to capture a SAML Trace.

Open

Capturing a SAML Trace

If a test user is not provided we will require a SAML Trace to be provided to complete SSO setups. A simple way to get a copy of a SAML assertion for SSO authentication is with the Firefox/Chrome plugin SAML-tracer. The plugin can be found here: SAML-tracer – Get this Extension for 🦊 Firefox (en-US) https://chrome.google.com/webstore/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch

• You'll want to download the plugin and enable it in Firefox/Chrome

• When the plugin is enabled, you'll see an orange SAML icon in the upper right corner of Firefox, click it to bring up the extension.

• In Firefox/Chrome, browse to your login URL with us, for this customer: _customer_URL_

• You will see scrolling information in the SAML-tracer window - that can be ignored for now.

• You will be redirected to their IDP login screen. You will need to enter credentials for a user in their system.

• When they attempt to log in, they'll be redirected to their login URL with us, but they won't be authenticated successfully as attributes have not been configured at this stage. This is the expected result.

• Now, in the SAML-tracer you will have a POST request to https://auth.ubiquia.com/Shibboleth.sso/SAML2/POST. You will need to select that request.

• After that request is selected, you'll see tabs in the lower half of the SAML-tracer window for HTTP, Parameters, and SAML - click the SAML button to select it. What's displayed in that window now is the full response the IDP sent to us for authentication. You can simply copy the whole response to us and we can identify the relevant information.

That's it! If you can get that information to us we can proceed with the setup and testing. Here is a screenshot with the relevant pieces of information identified with red boxes:

Open

Open

NOTE: If capturing a SAML trace using the plugins mentioned above is not an option, it is also possible to capture the SAML response base64 encoded in the browser. In Chrome it's done with developer tools → network tab → preserve log. Identify the 'POST' to our shibboleth server and find the SAML response in the headers. Once you have the SAML response, you can base64 decode in Notepad++ → Plugins → MIME tools → SAML converter or with a PowerShell command like: [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("base64encodedtext"))

Open

It's also possible to do this in other browsers, refer to: https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_saml_view-saml-response.html

Preferences Configuration

Once SSO is fully configured and tested then there are some additional questions that will need to be answered in regards to customer preferences (listed below). 

• Do you intend to use SSO for authenticating operational users (such as mailroom employees)?

• Do you intend to use SSO for authenticating operational users (such as mailroom employees) via Android handhelds?

• Do you intend to use SSO for authenticating pickup portal users (people that may receive deliveries, or request pickups but not necessarily employed in the mailroom)?

  • If yes, do you want our package tracking software to automatically remove old user accounts if a new user account with the same email is added?

  • Do you want it to remove old emails from packages if a new user account with the same email is added?

  • When logging in with an account that isn't in the system, do you want a new portal account to be created?

  • Whenever a new user is created, do you want the cost center view to be automatically enabled?

These settings are all optional. Please reach out to support for additional clarification on any of these options. 

Open

The customer will need to provide an SSO ID for any users they wish to authenticate using SSO, and for any recipients, they want to authenticate using SSO to the WTS Pickup Portal.  We recommend they import recipients with an SSOID value, using the column header 'ssoid' in their recipient import CSV file. If they are also using Cost Center View for their WTS Pickup Portal we would also recommend importing cost centers for their recipients via a CSV import file. Please reference the Importing Data Help Article

Open

Open

Once all users and recipients they wish to authenticate using SSO have an SSO ID defined and their preferences are selected the customer can proceed with using SSO as their authentication method to WTS.