SSO using Okta Workforce

Begin SSO Provider Setup in EchoMark

There are two ways you can use to initiate SSO Provider setup within EchoMark.

1. Use the “Set up Single Sign-On on EchoMark” email sent to you to configure SSO.
   1. Click on the Start SSO Configuration button in the email. Then, continue with Step 3 below. Note: if you start setting up SSO for an OIDC provider from the email link, either leave the link open while you setup your OIDC Client in your Identity Provider or make sure to use the same browser when re-opening the link to ensure you don’t create a duplicate entry.

2. If you already have an account setup, and are an Admin user in EchoMark, you can set up a new SSO provider through the EchoMark application.
   1. Log into the EchoMark application
   2. Go to the Settings page

3. Click on the Authentication link in the left Settings menu

4. There are two ways to setup the SSO provider from here. You can either invite an IT or SSO administrator to setup the SSO provider via an invite email or you can setup the SSO provider yourself.
   1. To invite an IT or SSO administrator to setup the SSO provider, click on the Invite IT admin to set up SSO provider button.

Fill in the IT/SSO administrator’s email address, and if desired modify or delete the additional personal message. Then click on the Send invitation button to send the email invitation.

2. To setup the SSO provider yourself, click on the Add SSO provider button.

3. In the following dialog, fill in the fields:
   1. Friendly name – Any friendly name you’d like displayed to differentiate this SSO provider from any others you may create.
   2. Provider Type – Select OKTA
4. Then, click on the Copy button to copy your Redirect URI to setup your application within Okta.

Create the Application in Okta

1. In a new browser or browser tab, log into the Okta Portal as an administrator.
2. In the left-hand navigation menu, go to Applications and Resources, then select Applications.

3. Click on the Create App Integration button at the top of the page.

4. On the Create a new app integration page, select OIDC – OpenID Connect as the Sign-in method, then select Web Application as the application type. Then click on the Next button.

5. Fill in the following information, then click on the Save button to continue.
   1. App integration name – Any name that will allow you to recognize the application is an SSO for the EchoMark application.
   2. Grant type – Ensure that Authorization Code is checked.
   3. Sign-in redirect URIs – This should be the Redirect URI that you copied from the EchoMark web application in Step 4
   4. Sign-out redirect URIs – You can enter in https://app.echomark.com (or your custom domain if you are a single-tenant customer).
   5. Assignments – You can select the option that best fits your organizational policies:
      1. Allow everyone in your organization to access – This allows all of your Okta users to log into the EchoMark application.
      2. Limit access to selected groups – Allows you to select one or more groups within Okta who will have access to the EchoMark application. Only users who belong to those groups will be able to log into the EchoMark application.
6. The application is now completed. Please copy and save the Client ID and Client Secret from the application page. You will need these to complete the EchoMark SSO setup.
7. Also please copy the URL for your Okta integration, as it is also required to complete setup. You can find this in the browser URL bar, or in the top right drop down by your name.
8. Complete the Okta setup for the requested scopes and permissions
   1. In the left-hand navigation menu, go to Security -> API to open the API settings page.
   2. Select the Default authorization server by clicking on the default link in the Authorization Servers tab. You can also optionally create a new authorization server if you’d like instead, then open the new server.
   3. Click on the Scopes tab to open the scopes page
   4. Click on the Add Scope button to add a new scope
   5. Fill in the following fields on the Add Scope dialog box:
      1. Name – groups
      2. Display Phrase – This can be set to any phrase you’d like to display the scope, such as “Groups”
      3. Description – Any description you’d like to add to be displayed with this scope such as “Allows the application to view a limited number of your group memberships”
      4. User consent – This can be left as Implicit, but if you’d like users to consent to it explicitly you can change this
      5. Block services – Leave this unchecked
      6. Default scope – Leave this unchecked
      7. Metadata – Leave this unchecked
      8. Click on the Create button to save your changes
   6. To ensure that your application has access to login, click on the Access Policies tab on the Authorization Server page
   7. If no policy exists already, click on the Add Policy button to add a new policy
   8. Fill in the following fields on the Add Policy screen:
      1. Name – Any name you can use to identify the policy
      2. Description – A description to help identify the policy’s purpose such as “Allows the EchoMark application to access Okta users”
      3. Assign to – The following clients: <The application created in steps 4 and 5>
      4. Then click on the Create Policy button to save the new policy
   9. Add a new rule to the policy to control the access tokens by clicking on the Add rule button towards the bottom\

5. Fill in the following fields on the Add Rule screen:
   1. Rule name – Any name you’d like such as EchoMark Application SSO
   2. IF Grant type is – Make sure that Authorization Code and Device Authorzation are checked.
   3. AND User is – Any user assigned the app
   4. AND Scope requested – Any scopes
   5. THEN Use this inline hook – None (disabled)
   6. AND Access token lifetime is – 1 Hours
   7. AND Refresh token lifetime is – 90 Days
   8. but will expire if not used every 7 Days
   9. Then click on the Create Rule button at the bottom to save the rule

Complete SSO Provider Configuration in EchoMark

1. Once you have created the application in the Okta portal, you can return to the Configure your SSO provider dialog in EchoMark and complete the SSO Provider setup by filling in the rest of the fields:
   1. Client ID – The client ID from your application in Okta from Step 6
   2. Client secret – The client secret from your application in Okta from Step 6
   3. Client secret expiration (optional) – If your client secret has a built in expiration date, you can fill it in here for tracking purposes. This is optional and does not affect the login process.
   4. Issuer – Your Okta domain from Step 7. Please make sure to prepend this with https:// if it’s not already included.
   5. Use federated logout (optional) – Sets the application to automatically log users out of Okta when they log out of EchoMark
   6. Email domains - Add in at least one email domain that should be associated with this SSO provider. Email domains will differentiate which SSO provider should be used to log into your EchoMark account. To add an email domain, enter the domain (such as “example.com”) in the box, and click on the Add button when it turns blue to indicate it is enabled.  Note domains must be unique across the environment, and must be associated with your company.
2. Then, click on the Continue button to save your configuration.

3. On the next screen, review the provider type, issuer, client ID, and email domain(s) associated with your Okta application. Then click on the Enable SSO and test button to enable the SSO provider. Note: Once you click on this button, this provider will be enabled immediately for testing purposes. You can disable it if needed after testing.
4. Verify that the login works. If this is the only SSO provider for your organization, or you are logged into the EchoMark application with a user of the same SSO provider, it is recommended that you just try to log in from an incognito or private browser window to avoid being locked out. Otherwise, you can click on the Open test sign-in button to open a new tab on the login page. This will log you out of your current session. In either case, once you verify that the login is working, click on the It worked button to complete the configuration. If login did not work with the new SSO provider, you can click on the It didn’t work – disable SSO button to disable the new provider.
   1. If the test was successful, you will see a confirmation dialog box. Click on the Done button to close it. Users can now login using the newly configured SSO provider.
   2. If the test is not successful, then clicking the It didn’t work – disable SSO button will immediately disable the new provider and bring up a confirmation box. You can click on the Done button to close it, or the Edit my configuration to return to the SSO provider configuration page to make changes and try again.