Single Sign-On (SSO) Configuration Guide

You will need an Okta account to begin. For testing purposes, Okta provides an unlimited free tier called the Starter Plan. See the Okta Getting Started guide for more information.

Create Users in Okta

1. Navigate to Directory > People.
2. Click Add Person.
3. Enter values into the fields for First Name, Last Name, Username and Email.
4. Once the user has been created, assign the user to the application by clicking the user's name, then clicking Assign Applications. 
5. Locate and select the OIDC application from the list.

Create and Assign Groups in Okta

1. Navigate to Directory > Groups.
2. Click Add Group.
3. Enter a name and description for the group. Take note of the group name as this will be used later.
4. Select the newly created group from the list, then click Manage People. This will display a list page where you can select the users who will be members of the group.

Add the Groups Claim

In order for the Mindful application to read your Okta groups, you'll need to do a bit more setup.

1. Navigate to Security > API. 
2. Click the default authentication server listed.
3. Click the Scopes tab, then click Add Scope.
4. Enter the following values, then click Create:

5. Next, click the Claims tab, then click Add Claim.
6. Enter the following values, then click Create:

For initial OIDC/Okta setup instructions, see the getting-started guide in the Okta Help Center.

Configure Okta

Once the OIDC application has been created, make sure the following configuration is in place:

1. Users and/or groups should be assigned to the application in the Assignments tab.
2. Make sure Authorization Code and Client Credentials are selected.
3. Obtain the appropriate value for Sign in Redirect URIs from the Mindful Support team.
4. In your OIDC application, navigate to the Sign On tab.
5. Click the Edit link next to the OpenID Connect ID Token section.
6. Make sure your section looks like the following and then click the Save button

Test the Access and ID Tokens

If you wish to test what your Access and ID Tokens will look like before integration, use the following steps:

1. Navigate to Security > API. Select the default authorization server.
2. Select the Token Preview tab.
3. Enter information into the required fields. 
   1. Select your OIDC app from the list in the OAuth/OIDC Client field.
   2. In the User field, enter a user that you created in your Dashboard. 
4. Click Preview Token.

Configure your Mindful Organization for OIDC using Okta

Now it's time to link your Mindful Organization to your Okta OIDC account. This step can only be performed by Mindful staff. 

Add Role Mappings (Okta to Mindful)

Lastly, you'll need to map your Okta group to Mindful roles.

1. Click Add Role Map.
2. For Name, enter the same value that you used for your Okta group. Exact capitalization isn't required.
3. For Roles, enter the role(s) that the user will be assigned when they log in with a matching group name.
4. If more roles are necessary, add those as well. Make sure to click Save to keep your changes.

Set up SAML in Okta

1. Navigate to Applications and click Create App Integration.
2. Select the SAML 2.0 radio button, then click Next.
3. Under App Name, enter whatever value you would like, then click Next. 
4. For Single sign on URL, enter the appropriate URL provided by the Mindful Support team.
5. Click Use this for Recipient URL and Destination URL.
6. Set the Audience URI(SP Entity ID) to the appropriate value. Contact the Mindful Support team to obtain the Cognito User Pool ID that will be used in the Audience URI for this field.
7. Set the Application username to Email.
8. Attribute Statements: Add a new entry:
   • Name: Enter http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   • Name format: Select Unspecified.
   • Value: Enter user.email
9. Group Attribute Statements: Add a new entry:
   • Name: Enter http://schemas.xmlsoap.org/ws/2005/05/identity/claims/groups
   • Name format: Select Unspecified.
   • Filter: Select Matches regex with a value of .*
10. Click Next.
11. Select I'm an Okta customer adding an internal app.
12. Select This is an internal app that we have created.
13. Click Finish.
14. Make sure your users and/or groups are assigned to the application by going to the Assignments tab and selecting users/groups.

Configure your Mindful Organization for SAML using Okta

Now it's time to link the Mindful Organization to your Okta SAML account. This step can only be performed by Mindful staff. 

Add role mappings (Okta to Mindful)

Now you will need to map your Okta group to Mindful roles.

1. Click Add Role Map.
2. For Name, enter the same value that you used for your Okta group. Exact capitalization isn't required.
3. For Roles, enter the Role or Roles that the user will be assigned when they log in with a matching Group name.
4. If more roles are necessary to map, add those as well. Make sure to click the Save button to persist your changes.

SAML Single logout in Okta

When enabled, this will result in a Mindful UI logout also logging out of Okta. It works by Cognito redirecting the UI to Okta after the Cognito logout, with a specially formatted SAML logout package on the query string sent to Okta. Okta verifies this SAML package using the issuer string and a public SSL cert key, and if valid, logs out the user.

To enable:

1. In Cognito UserPool > Identity Provider, Enable Sign Out flow.
2. In Okta > Applications > Edit > SAML Configuration > Edit, select Show Advanced Settings.
3. Select the Enable Single Logout setting.

Next, complete the form as follows:

1. Single Logout URL: Enter the appropriate value provided by the Mindful Support team.
2. SP Issuer: Enter urn:amazon:cognito:sp:<user pool id>
3. Signature Certificate: Obtain the Signing Certificate from the Cognito AWS console, then format it to .crt format. Otherwise, Okta won’t accept it.
   1.  Add the correct header/footer.
   2. Insert line breaks every 64 characters. 
   3. Save the file with a .crt extension.

-----BEGIN CERTIFICATE-----

MIICvDCCAaSgAwIBAgIIOc0ggmd46TMwDQYJKoZIhvcNAQELBQAwHjEcMBoGA1UE

AwwTdXMtZWFzdC0xX3ZVbXlKcUVSZjAeFw0yMjA3MTgxNzU0MzRaFw0zMjA3MTgx

...etc...

fDAL+E3i7TTP9TVZkUt0hKaUGi3/SMF3xrMVVITLrTqYhZzHq+PtPMqZBb8ugI6N

+mMIF6JDN7OiU5y2ARg6xdB4t5gl04GjdbI9cIEGaOo=

-----END CERTIFICATE-----

You can use this article from Auth0 to get started creating an Auth0 application. The steps below cover creating users and managing roles.

Create users in Auth0

1. Navigate to User Management > Users and click Create User.
2. Enter the fields (all are required) in order to create the user:

Create and Assign Roles in Auth0

1. Navigate to User Management > Roles and click Create Role.
2. Enter a role name and description. Take note of the role name for later use.
3. From either the Userslist page or the Roleslist page, you can link users to roles.

Add the Role Claim

In order for the Mindful application to read your Auth0 role, we have to do some setup to make sure they can be read.

1. Navigate to Actions > Library.
2. Click Build Custom at the top.
3. Give the new Action a name and make sure the Trigger is Login/Post Login. This will run some custom code on a user's login that will add the role claim to the id and access tokens.
4. Once created, you will be presented with a code window. Enter the following into the code window and click Deploy. The namespace variable will need to be whatever is appropriate for the customer:

/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are
logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the
behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
    const namespace = 'https://getmindful.com' // this should be whatever the company
domain is
    if (event.authorization) {
        console.log('Setting authorization: ',event.authorization );
        // USE THESE TWO LINES FOR OIDC
        api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
        api.accessToken.setCustomClaim(`${namespace}/roles`,
    event.authorization.roles);
        // USE THESE TWO LINES FOR SAML
        api.idToken.setCustomClaim(`roles`, event.authorization.roles);
        api.accessToken.setCustomClaim(`roles`, event.authorization.roles);
    }
}

Set up OIDC in Auth0

1. Navigate to Application > Applications.
2. Make sure Allowed Callback URLs, Allowed Logout URLs, and Allowed Web Origins contain the correct URLs provided by the Mindful Support team.
3. Under Advanced Settings > Grant Types, make sure Implicit , Authorization Code and
   Refresh Token are selected.

Configure Your Mindful Organization for OIDC Using Auth0

Now it's time to link the Mindful Organization to your Auth0 OIDC account. This step can only be performed by Mindful staff. 

Add Role Mappings (Auth0 to Mindful)

Now we need to map our Auth0 role to Mindful roles.

1. Click Add Role Map.
2. For Name, enter the same value that you used for your Auth0 role. Exact capitalization isn't required.
3. For Roles, enter the Role or Roles that the user will be assigned when they login and have a matching Rolename.
4. If more roles are necessary to map, add those as well. Make sure to click Save to keep your changes.

Set up SAML in Auth0

If you followed the instructions for setting up an OIDC application, the additional setup for SAML is simple.

1. Go to Applications > Applications and select your application.
2. Open the Addons tab.
3. Enable the SAML2 WEB APP addon. 

4. In the modal window that appears, click the Settings tab and make sure the Application Callback URL is configured properly. Contact the Mindful Support team to obtain the correct URL.
5. Click Enable or Save.

Configure Your Mindful Organization for SAML Using Auth0

Now it's time to link the Mindful Organization to your Auth0 SAML account. This step can only be performed by Mindful staff. 

Add Role Mappings (Auth0 to Mindful)

Now you need to map your Auth0 role to Mindful roles.

1. Click Add Role Map.
2. For Name, enter the same value that you used for your Auth0 role. Exact capitalization isn't required.
3. For Roles, enter the Role(s) that the user will be assigned when they log in with a matching Role name.
4. If more roles are necessary to map, add those as well. Make sure to click Save to keep your changes.

For instructions on configuring Azure AD, see this getting started guide from Azure.

Add Users

1. Navigate to Azure Active Directory > Users, then click New User.
2. Fill in the required fields to create a new user. If Groups or Roles are already configured, you can link those here as well.

(Optional) Set up Application Roles

There are two group concepts in Azure AD: Groups and Application Roles. Either one can be sent as a custom claim to Mindful, but each has its own configuration requirements. Regardless of the method you choose, you will still need to assign users to your application.

1. From your Azure active directory select App registrations.
   
2. Navigate to your application.
3. Click App roles, then click Create app role. Make sure Allowed member types is set to Users/Groups or Both.
   

Assign Users to Groups

1. Navigate to Users.
2. Click the user you wish to update.
3. Click the Groups side navigation link.
4. Click add memberships.
5. Select the user(s) you wish to add to the group.

Assigning Users to Your Application

1. Navigate to Enterprise Applications > Your application.
2. Click Assign users and groups, then click Add user/group.
3. Select the user(s) you wish to assign the role.
4. Select the application role you wish to assign to the user(s). This can be the default user role if you're not using groups.

5. Click Assign.

This will add another row to the Users and groups list. You should see the new row with your assigned role.

Set up OIDC in Azure AD

1. Navigate to Azure Active Directory > App Registrations and click New Registration.

2. Here we configure the application's Redirect URI. Contact the Mindful Support team for the correct URI.
3. Create the application. Once the application has been created, take note of the Application (client) ID and the Directory (tenant) ID. Both will be used later for the client ID and issuer, respectively.

4. Navigate to your OIDC application and click Certificates & secrets.
5. Next, click New Client Secret.
6. Copy the value of the generated client secret.

Generate a Client Secret

1. Navigate to your OIDC application from Azure Active Directory  > App Registrations. 
2. Click Certificates & secrets, then click New Client Secret.
3. Enter a description and an expiration date (defaults to six months).
4. Copy the value of the generated secret (not the secret ID) as this will be used later and cannot be retrieved again without regenerating another secret.
   • Store this value somewhere secure for reference later (If you missed this step you can delete the current secret and generate another in order to copy the value).

Add Group Claims to the application

1. Navigate to your OIDC application.
2. Click Token Configuration.
3. Click Add groups claim and make sure the following is selected. This should allow the groups claims to come across in the ID token, Access Token and SAML attributes.

Add Application Roles to OIDC

1. From your Azure active directory, select App registrations.

2. Navigate to your application.
3. Click App roles, then click Create app role. Make sure Allowed member types is Users/Groups or Both.

Assign Users to OIDC

1. Navigate to Enterprise Applications > Your application.
2. Click Assign users and groups, then click Add user/group.
3. Select the user or users you wish to assign the role.
4. Select the application role you wish to assign to the user or users. This can be the default user role if using groups.

5. Click Assign.
6. This will add another row to the users and groups list. You should see the new row with your assigned role.

Configure your Mindful Organization for OIDC using Azure AD

Now it's time to link the Mindful Organization to your Azure AD OIDC application. This step can only be performed by Mindful staff. 

Add Role Mappings (Azure AD Group to Mindful)

Now you need to map your Azure AD Group to Mindful roles.

1. Click Add Role Map.
2. If you are using Azure AD Groups: For Name, enter the Group ID of the group you created in Azure AD. The Group ID can be found by going to Azure > Groups. Select the group and look for an Object ID field. This is the UUID (aka Group ID) for the group. If you are using Azure Application Roles, enter the name of the role you created and assigned to your users.
3. For Roles, enter the role or roles that the user will be assigned when they log in with a matching Role name.
4. If more roles are necessary to map, add those as well. Make sure to click Save to keep your changes.

Set up SAML in Azure AD

1. Navigate to Azure Active Directory > Enterprise Applications, then click New Application.
2. Select Create your own application.
3. Name the application and make sure Integrate any other application you don't find in the gallery is selected.
4. Once created, you will be taken to the application Overview page.

5. Click Set up Single Sign-On and choose SAML.
6. The first box will have two required entries. Select the Edit button for this first box.

7. The Identifier(Entity ID) will be the Cognito user pool URN. Contact the Mindful Support team to obtain the correct value. 
8. The Reply URL will be the callback URL to Mindful. Contact the Mindful Support team to obtain this value, as well.

Add Group Claims

1. In the second box in the Set up Single Sign-On with SAML section, click the Edit button.
2. Click Add a group claim.
3. Select which groups are to be included in the claim. This will depend on the client's requirements, but All Groups is a good selection for testing. The Source attribute should be Group ID.

Add Application Roles to SAML

1. From your Azure active directory, select App registrations.

2. Navigate to your application.
3. Click App roles, then click Create app role. Make sure Allowed member types is Users/Groups or Both.

Assign Users to SAML

1. Navigate to Enterprise Applications > Your application.
2. Click Assign users and groups, then click Add user/group.
3. Select the user or users you wish to assign the role.
4. Select the application role you wish to assign to the user or users (Can be the default user role if using groups).

5. Click Assign.
6. This will add another row to the Users and groups list. You should see the new row with your assigned role.

Add the Application Roles Claim

1. In the second box in the Set up Single Sign-On with SAML section, click Edit.
2. Click Add new claim.
3. Name the new claim roles.
4. The Source should be Attribute.
5. The Source attribute field should be user.assignedroles

Configure your Mindful Organization for SAML using Azure AD

Now it's time to link the Mindful Organization to your Azure AD SAML account. This step can only be performed by Mindful staff.

Add Role Mappings - Azure AD Group to Mindful

Now we need to map our Azure AD Group to Mindful roles.

1. Click Add Role Map.
2. If you are using Azure AD Groups: For Name, enter the Group ID of the group you created in Azure AD. The Group ID can be found by going to Azure > Groups. Select the group and look for an Object ID field. This is the UUID (aka Group ID) for the group. If you are using Azure Application Roles, enter the name of the role you created and assigned to your users.
3. For Roles, enter the Role or Roles that the user will be assigned when they log in with a matching role.
4. If more roles are necessary to map, add those as well. Make sure to click Save to keep your changes.