Okta is a 3rd party authentication service that provides SAML integration for companies. L2L Dispatch can easily be added to Okta as an Application to provide SSO functionality for Dispatch users who have Okta accounts. When SAML authentication for Dispatch is enabled, the dispatch login page will have a button that the user can use to initiate SSO authentication, or users can use their Okta home page to access their configured applications.
This document explains how to configure Dispatch and Okta to interoperate using SAML for authentication. In the examples, the Dispatch server will be acme.leading2lean.com, and Acme-L2L-Dispatch will be the name of the Okta application that we create.
You must have administrative access to both Dispatch and your Okta account to complete these steps. Your users must already have accounts in Okta and you will need to assign this new application to them.
Step 1: Create the Dispatch SAML Config
We first create a new SAML Config that defines the SAML Trust between Dispatch and the Okta application. Log in to acme.leading2lean.com, and navigate to Setup -> IT Setup -> SAML SSO Config at https://acme.leading2lean.com/setup/samlconfig/. Click the Add New link.
In the Add New SAML Config page, we will enter the following information:
- Code: this must be a unique code among all the Dispatch SAML Config’s and gets used in the Dispatch SAML URL’s. For this example, we will use the code acme-okta-sso.
- Display Name: This is user visible text on the Dispatch login page – we will use Dispatch ACME Okta SSO for this example
- IdP User Naming Attribute: You need to choose how users will log into Dispatch. Choosing email requires that the Dispatch user accounts have their email addresses set to the same email address set on users’ Okta accounts, and choosing username requires that the Dispatch username matches the Okta username.
Leave all the other fields blank for now and click save. Now click on the new SAML Config again, and copy the SP Entity ID and the SP Initiate URL’s, as we will use both url’s in the next step.
Step 2: Create the Okta Application
We now create a new Application in our Okta account. Do the following to create a new Application:
- Log into Okta as an Administrator
- Click on the Applications header link
- Click on the Add Application button
- Click on the Create New App link
- In the Create a New Application Integration dialog, set the Platform to Web, and choose SAML 2.0 as the Sign on method, then click the Create button.
- Choose an App name – for this example we will use Acme-L2L-Dispatch, then click Next.
Now in the Configure SAML Step, set the following settings after deciding if you want your users to log in to Dispatch with their Okta username or their email address:
- Single sign on URL – Set this to the Dispatch SAML Config’s SP SSO URL
- Use this for Recipient URL and Destination URL - Checked
- Audience URI – Set this to the Dispatch SAML Config’s SP Entity ID
- Name ID format – Set to Email Address if you are using email addresses, otherwise leave it as unspecified
- Application username – Set to Email if you are using email addresses, or choose one of the username options.
All other fields can be left empty or with their defaults. Now click Next. In Step 3, select that you are a customer adding an internal app and no other fields need to be set. Click Finish to save the Application, then click on the View Setup Instructions link. This new page has information we need to store in the Dispatch SAML Config.
Step 3: Update the Dispatch SAML Config
Now in your Dispatch web session, view the acme-okta-sso SAML Config we previously created. We now will fill out the following fields:
- Set the IdP Entity Id field to the Okta Application’s Identity Provider Issuer value.
- Set to the IdP SSO URL to the Okta Application’s Identity Provider Single Sign-On URL.
- Copy the Okta Application’s X.509 Certificate string and store that in the Dispatch SAML Config’s IdP Certificate Information field as the x509 Public Certificate in PEM format.
Now click the Save button for the Dispatch SAML config. Your SAML configuration is now ready to use.
Step 4: Migrate Dispatch Accounts to use SAML Authentication
If you need to migrate most/all of your Dispatch accounts to use SAML authentication, there are Dispatch tools to make this easy. Each Dispatch SAML Config has a Migrate Accounts button that allows you to perform a bulk migration for users to use the SAML Config. Simply click the button and follow the instructions to enable your user accounts to authenticate using SAML.