Single Sign On (SSO) with Okta

Introduction

Single Sign On (SSO) allows users to sign in once across multiple applications, sites and platforms.

Vertex have created an integration with Okta, an identity provider for SSO. Vertex acts as a service provider, storing the users from your merchant's account with Okta.

For more information about Okta, see https://www.okta.com.

This has the following benefits:

Role assignments are done in Okta.
Security is optimized because Taxamo (as the service provider) stores all the user information with Okta (the identity provider). This means that Vertex cannot see your users' data.
Single LogOut (SLO) is also implemented. This allows users to log out from the identity provider (Okta) by logging out of the service provider (Vertex).

Two types of login are possible after you complete the configuration:

Service Provider (SP) initiated: This is when a user logs in using the Vertex dashboard. This requires the Organization ID and a login through Okta.
Identity Provider (IdP) initiated: This is when a user logs in using the Taxamo app in Okta.

Enabling SSO

To enable this feature for your merchant account, you need to sign up for it. To do so, contact the sales team at [email protected] or your account manager .

After this has been done, complete the following steps to enable the feature:

Log in to the Merchant Portal.
Click SETTINGS.
Under Security Options, click Enable additional security options. The SSO SAML Confguration UI is displayed:

If a configuration exists, you can save or delete it.
To create a new configuration, click +Add configuration.

Configuring SSO

To configure the feature, complete the following steps:

To create a new SSO configuration in Vertex, complete the following steps:
a. Log in to the Merchant Portal.
b. Click SETTINGS.
c. Under Security Options, click SSO SAML Configuration.
d. To create a new configuration, click +Add configuration.
e. Complete the information for the sections outlined in the table:

Section	Description
Organization ID	Enter the ID that will be used for SP-initiated logins.
Service Provider	Enter the Taxamo data that is used by Okta.
Identity Provider	Enter the Okta data here.

Set up Taxamo (service provider) in Okta (identity provider)
a. Go to https://developer.okta.com/ and register.
b. Log in to your Okta account.
c. Ensure that the Classic UI option is selected. You can check this in the top left hand corner of the screen.
Create a new application.
a. Click Applications -> Add Application.
b. Click Create New App and enter the following details:

Field	User Entry
Platform	Web
Sign-on method	SAML 2.0

c. Click Create.
d. Enter the business name. For example My Business.
e. To allow IdP-initiated logins, ensure that the following checkboxes are not selected and click Create:

Do not display application icon to users
Do not display application icon to users in the Okta mobile app.

Complete the remaining fields.
a. Enter the following settings:

Field	User Entry
Single sign on URL	Specify the Assertion Consumer Service URL from your Taxamo configuration.
Audience URI (SP Entity ID)	Specify the Entity ID from your Taxamo configuration.
Name ID format	Set this to one of the following: EmailAddress Transient
Application username	Enter email as the user name.

b. Click Show Advanced Settings.
c. In the Assertion Encryption field, choose encrypted.
d. To load the encryption certificate, copy the Service Provider x509 certificate from your Vertex configuration.
e. Complete the following settings:

Field	User Entry
Allow application to initiate Single Logout	Ensure that this checkbox is selected.
Single Logout URL	Enter the URL from your Taxamo configuration.
SP Issuer	Specify the SP Entity ID from your Taxamo configuration.

f. Load the same certificate that you used for assertion encryption.

Add the group attribute statements. This step is optional:
a. Enter the following information:

Field	User Entry
Name	taxamo_groups
Filter	Matches regex
Value	taxamo_.*

c. Click Next.
d. Choose I am an Okta customer adding an internal app and click Finish.

Set up Okta in Vertex.
a. Click View Setup Instructions.
b. To copy the data to the Identity Provider configuration in Vertex, copy and paste the certificates.
c. Specify an Organization ID. This value is used for signing in later on.
d. Save the configuration.
Assign the application to yourself.
a. Go to Directory -> People.
b. Click on your name and click Assign Applications.
c. Select the app and click Assign.
d. Click Save and Go Back.
Create a new group.
a. Go to Directory -> Groups.
b. Click Add Group.
c. Enter taxamo_developer in the Name field.
Assign yourself to the group.
a. Click the group name.
b. Click Manage People.
c. Click on your name and click Save.

Troubleshooting

If you cannot login to Okta, even though you have entered the correct user name and password, ensure that you are logged out from https://www.okta.com and https://developer.okta.com/.

If you cannot view the SSO SAML configuration section in your account security settings, contact your Taxamo account manager to check that the settings are enabled.