SSO using OIDC (Open ID Connect)

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 (Step 4) 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 OIDC
4. Then, click on the Copy button to copy your Redirect URI to setup your OIDC Client within your Identity Provider.

Create the OIDC Client in your identity provider

1. In a new browser or browser tab, log into your Identity Provider and setup a new OIDC client. 
   1. You can use the Redirect URI from step 4 as the Redirect URI or Callback URI for setting up your provider.
   2. If you need to choose a client type, you can select Authorization Code for the client type. This may also be a web application client or similar.
   3. You will need to save the following information from your Identity Provider:
      1. Client ID
      2. Client Secret
      3. Issuer
      4. Either the Well-Known configuration path (i.e. https://[identityprovider]/.well-known/openid-configuration) or the paths to the following OIDC endpoints for your Identity Provider:
         1. Authorization Path (i.e. https://[identityprovider]/oauth2/default/v1/authorize)
         2. Token Path (i.e. https://[identityprovider/oauth2/default/v1/token)
         3. User Info Path (i.e. https://[identityprovider]/oauth2/default/v1/userinfo).
      5. Optional (Advanced) – EchoMark assumes you are using standard OIDC claims in your access token, especially using the sub claim for the unique user identifier, the email claim for the user’s email address, and the name claim for the user’s name. If any of these are not the case (unlikely), please get the proper claim names.

Complete SSO Provider Configuration in EchoMark

1. Once you have created the OIDC client in your Identity Provider, 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 Identity Provider
   2. Client secret – The client secret from your Identity Provider
   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 – The issuer defined by your Identity Provider.
   5. Use federated logout (optional) – If you would like to log your users out of your SSO provider when they log out of EchoMark, you can check the Use federated logout box, and then fill in the URL of your identity provider’s logout endpoint in the box that appears. Users will automatically be logged out of their identity provider when they log out of EchoMark.
   6. Well-known path – If you have a well-known path from your identity provider, fill it in here. If you do not have a well-known path, you can uncheck the Use well-known endpoint in order to fill in the Authorization Path, Token Path, and User Info Path manually.
   7. ID Claim (optional) – If your ID claim is not standard, you can fill in the correct claim name here.
   8. Email claim (optional) – If the email claim for your identity provider is not standard, you can fill in the correct claim name here.
   9. Name claim (optional) – If the name claim for your identity provider is not standard, you can fill in the correct claim name here.
   10. Role claim (optional) – If you are a single tenant customer, and have a role claim that is not standard, you can fill in the correct claim name here. SaaS customers can ignore this field.
   11. 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 the SSO provider. 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.