Okta SAML Setup Guide

Introduction

Overview

The bigtincan hub appliance supports SAML 2.0 authentication and is able to act as a Service Provider, allowing customers to leverage their own authentication systems. 

Bigtincan hub has one endpoint, used for all hub interfaces.

When users attempt to log onto the bigtincan hub instance they will be automatically redirected to the specified Identity Provider (IdP) and will return to where they left off.

Terminology

Term

Meaning

IdP

Identity Provider

SP

Service Provider (the bigtincan hub API server)

<hub domain>

The domain / DNS name that the bigtincan hub instance is reachable on.

e.g. 

https://[dns_alias].push.bigtincan.com (for a company on the bigtincan USA cloud systems)

https://[dns_alias].push.bigtincan.com.au (for a company on the bigtincan APAC cloud systems)

https://[dns_alias].push.bigtincan.co.uk (for a company on the bigtincan EU cloud systems)

Note: this must be exactly the same as the servers configured _APP_URL (set up at server configuration time. Should be a fully qualified domain name)

SSO

Single sign on

SLO

Single log out

ACS

Assertion Consumer Service

Setting up the Identity Provider

The IdP setup process varies depending on the vendor software being used. An Idp will generally require the following details:

Endpoint settings

Entity ID

<hub domain>/saml/metadata

SSO URL

<hub domain>/www/index.php?url=/saml/acs

General settings

Name ID Format

EmailAddress

Responses

Signed

Assertions

Signed

Authentication Context Class

X.509 Certificate

Service Provider Public Certificate

This can be retrieved from the bigtincan hub instance while logged in as a Superuser via:

SAML Config > Download public certificate link.

 

If “Certificate Status” is not set then generate a certificate using the “Generate Certificate” button, or upload your own set.

Required attribute statement settings

Please note that all field key names support the following formats:

  • snake_case
  • PascalCase
  • camelCase

Field 

Example field names

Name format

Value

First name

first_name 

FirstName 

firstName

Unspecified

User’s first name

Last Name

last_name

LastName

lastName

Unspecified

User’s last name

Email Address

email

Email

Unspecified

User’s email address

Optional attribute statement settings

Field

Example field names

Name format

Value

Configuration bundle

configuration_bundle

ConfigurationBundle

configurationBundle

Unspecified

Configuration bundle ID retrieved from the bigtincan hub instance via:

Company Details > Configuration Bundles list

Groups

groups

Groups

Unspecified

Formats supported:

  1. An array of group names. 
  2. A semicolon separated list of group names
 

These groups must be created on bigtincan hub before they can be assigned to a user.

 

Group assignments are only processed when a user is first created via their initial login. Once their user has been created, this attribute will not have an effect.

Metadata

metadata

Metadata

Unspecified

JSON metadata string; used to link SAML users to metadata in bigtincan hub.

 

Example input:

 

'{"Brand":["ABCMart","ON"],"Region":["North","Inner West"],"Suburb":["Cronulla","Parramatta"]}'

Setting up Okta using Bigtincan pre-built application:

  1. Open Okta and go to Admin window > Applications > Add Application:
  2. Search for Bigtincan, click Add:

3. Fill out the form as shown below:

a. Application label: This can be anything you like e.g. Bigtincan

b. ACS URL: https://[yourcompanyname].push.bigtincan.com/www/index.php?url=/saml/acs

Audience Restriction: https://[yourcompanyname].push.bigtincan.com/saml/metadata

4. Assign Users:

5. Hit NEXT, then click Done.

6. Next, still in Okta, click on Sign On:

7. Scroll down to where you see Identity Provider metadata:

8. Click Identity Provider Metadata and it will download a file called metadata.

9. Open the file in a text editor on your desktop and save the file as: Okta_BTC_Metadata.xml. 

10. Login to app.bigtincan.com

11. Click on the gear at the bottom right of the first page called “Tenant Configuration”

12. Click on Security:

13. Choose DNS and make sure for your DNS Alias is set to: [yourcompanyname].push.bigtincan.com

14. Then click on Authentication > SAML and scroll to Metadata file and click Select File:

15. Choose the file you saved earlier: Okta_BTC_Metadata.xml. 

16. Then click SAVE at the top right corner:

17. To Test, open a web browser and enter the URL: [yourcompanyname].app.bigtincan.com

18. This should take you to our enterprise login page, click “Sign-In” and you should be taken to your SSO login page.

19. Login on the SSO login page and you should be taken to your BTC home tenant page. (Note: This is my personal domain so the URL will be different from yours):

20. Single Sign On through SAML to Bigtincan is now setup.


Setting up Okta for Appnext:

1. Open OKTA and go to Admin window > Applications > Add Application
2. Click Create New App
3. Choose Platform=Web; Sign On Method=SAML 2.0. Click Next
4. Create a name for the app and upload a logo if you need one, please reach out and we can send one to you. Click Next
 

5. Enter the Single Sign On URL, Recipient URL and Destination URL which are all the same

Make sure that "Use this for Recipient URL and Destination URL" is unchecked

- Single Sign On URL: https://companydomain.push.bigtincan.com/www/index.php?url=/saml/acs
- Recipient URL: https://companydomain.push.bigtincan.com/www/index.php?url=/saml/acs
- Destination URL: https://companydomain.push.bigtincan.com/www/index.php?url=/saml/acs
Audience Restriction: https://companydomain.push.bigtincan.com/saml/metadata
- Default Relay State:
https://companydomain.push.bigtincan.com/webapi/auth/login?
auth_type=saml&redirect_referrer=https://companydomain.appnext.bigtincan.com

Name ID Format: Unspecified
Response: Signed
Assertion Signature: Signed
Attribute Statements

Hit Next and complete page 3:

Add users to your app, export the metadata and enter it on the Bigtincan side as shown previously.