Enable Okta SAML and SCIM in Lucid

Supported features

SAML SSO Capabilities:

• SP-initiated SSO
• IdP-initiated SSO
• JIT (Just-In-Time) Provisioning

SCIM Provisioning Capabilities:

• Create Users
• Update User Attributes
• Deactivate Users 
• Push Groups

Configure the SAML integration for Lucid

Follow the below instructions exactly regardless of whether you are using Lucidchart, Lucidspark, or both.

In Lucid:

1. Select Admin.
2. Click Security in the left-hand menu.
3. From the dropdown, select Authentication.

4. Select Configure to the right of the “Allow SAML authentication” option to navigate to your SAML Activation page in Lucid. You will not be able to use SAML until you have populated your domain and uploaded metadata.

   

5. Under "Lucid sign-in URL," enter your Domain name.
   • Ensure the domain you are using is not already in use, since it is used to uniquely identify your account during SSO.
     
6. Click Save changes.
7. Copy the ACS URL from Lucid (it will be needed in Okta).

In Okta:

1. Browse the Okta Integrations Network and search “Lucid”.
   • After you have added the Lucid app to Okta, you can configure the SAML integration so that end users on your Okta instance can authenticate using SAML sign-on through Okta. 
2. In the General Settings section of the Lucid for admin management app in Okta:
   • Paste the ACS URL from Lucid in as the “SAML URL”
   • Select whether you would like to display "diagramming" and/or "whiteboarding". Each will appear in your users app gallery to facilitate IdP-initiated sign-on.
     
3. In the "Sign On" tab of Okta, navigate to SAML Signing Certificates.
4. Click Actions.
5. Select View IdP metadata.
   
6. Download the metadata by right-clicking anywhere on the XML page, selecting Save As, and saving it as an XML file (e.g., “metadata.xml”). 
   • This XML file (metadata) contains instructions that Lucid will need to communicate with Okta. You will upload the saved file to Lucid.
     

In Lucid:

1. Open the Lucid admin panel.
2. Click App integration from the navigation on the left side.
3. Select General from the navigation options.
4. Under "Enabled integrations", click Settings from the "SAML" tile.
5. Scroll down on the SAML Activation page and click + Add identity provider to upload the XML file you downloaded from Okta.
   • The metadata will populate the following fields:
     
6. Click Test SAML connection to verify that Lucid is properly communicating with Okta. 
   • The connection will only work if the Lucid for admin management app has been assigned to your test user in Okta. You can assign the app to users in the Assignments section of the app page.
   • The test may fail if you have not enabled SAML as an authentication method. If this occurs, navigate to the Authentication page in the Security settings of your Lucid admin panel, and verify “Allow SAML authentication” is checked.
     

You have the option to use encrypted assertions for the identity providers you add for SAML to your Lucid account. To learn more, refer to our SAML overview article.

Create users upon login with SAML

Once you have configured SAML with Okta for your Lucid account, you can set up Just-In-Time (JIT) provisioning so that users assigned Lucid access in Okta who do not have a Lucid account will have an account created for them upon their first login.

Note: For JIT provisioning to work as intended, you should have domain control enabled and have the user verification method set to SAML.

You can customize Just-In-Time provisioning in the license settings section of your Lucid admin panel, depending on the access you want users to have. Here are the options:

• If you would like all users to come onto your Lucid account with full-edit licenses, choose the following settings:
  • Under the “Access eligibility” section, select Eligible for full access.
  • Under “Customized eligibility criteria”, select Instant access.
• If you want all users to come in as limited-access users, under the “Access eligibility” section select Only eligible for limited access.
  • Your users will still be able to request full-edit licenses. Depending on the “When a user requests a license” setting, you can automatically grant licenses to users upon their request, or you can turn those requests into pending requests in your user list.

Add user attributes via Just-in-Time (JIT) provisioning

JIT provisioning uses the SAML protocol to create a Lucid user when someone assigned Lucid access in your Okta instance logs in to Lucid for the first time. You can also configure SAML to send additional attributes to Lucid for these users, such as the user's first name, last name, and email address.

Follow these steps to configure first name, last name, and email attributes:

1. Log in to your Okta account.
2. Navigate to the Lucid for admin management app in Okta
3. Select the Sign On tab.
4. In the upper-right corner of the Sign On section, select Edit.
5. Click the arrow to the left of “Attributes (Optional)” to expand the menu.
6. Configure a user’s first name:
   • Add a title to the name field. This value doesn’t have to match the Value dropdown section.
   • In the name format field, select Unspecified from the drop-down list.
   • Click on the drop-down menu beneath “Value”.
   • Select user.firstName from the dropdown.
7. To add another field click Add Another.
8. Repeat the instructions for last name and email with the specified name field and value field expressed below:
   • To add a user’s last name:
     • Add a title to the name field.
     • Select user.lastName from the Value fields dropdown
   • To add a user’s email:
     • Add a title to the email name field.
     • Select user.email from the Value field dropdown
9. After adding the user attributes described in these steps, you can expect your Okta page to look like this:
10. Scroll to the bottom of this inner window.
11. Click Save.

Now, when a user signs in for the first time and creates their Lucid account, they will have their first name, last name, and email address values properly set up.

Configure SCIM for the Lucid Suite in Okta

To create users before their first login through Okta, set up the Lucid SCIM integration by following the steps below.

Before configuring SCIM, confirm that you are on an Enterprise account with an up-to-date pricing plan. To upgrade, contact sales.

Once you have followed the pre-configuration steps listed above, you can configure both SCIM for admin management and SCIM for content access apps for the Lucid Suite in Okta by generating separate bearer tokens in Lucid and then using them in Okta. To learn more about the differences and value of each app, refer to our SCIM overview for Lucid article.

Enable SCIM and generate a bearer token in Lucid

1. Log in to Lucid as an account owner or account admin.
2. Select Admin from the menu to the left.
3. Select App integration in the left-hand navigation menu.
4. On the relevant SCIM tile, select Settings (or Install).
   • To set up both apps, you will need to separately follow the remaining steps for SCIM for admin management and SCIM for content access. You will generate a separate bearer token for each app.
5. Under the bearer token section, click Generate token.
   • The Lucid base URL and bearer token will be needed for the next steps in Okta.

Configure integration(s) and use bearer token(s) in Okta

Depending on whether you are looking to use SCIM for admin management, SCIM for content access, or both, the steps here will slightly differ.

Configuration for SCIM for admin management

1. Log in to Okta as an admin.
2. Open the Okta Admin Console and navigate to your Lucid app.
3. Under the "General" tab, under the "App Settings" section, add the SCIM Base URL.
   
   • This URL can be copied directly from the SCIM for admin management page in Lucid.
     
4. Under the "Provisioning" tab, click Configure API Integration.
5. Check the box next to "Enable API Integration". 
   • A text field will appear where you can add your bearer token that was generated by Lucid.
     
6. Paste the bearer token generated by Lucid from the SCIM for admin management into the API token field.
   • Keep in mind that if you are setting up both Lucid SCIM apps, this is a separate bearer token from the SCIM for content access token. Be sure to use the correct one with each app.
7. Make sure “Import Groups” is not checked (unless you want your existing Lucid org groups imported to Okta).
8. Click Save.

Once the Lucid and Okta connection is established, you can start using the SCIM connection to provision users and groups and manage licenses. See the sections below for further information.

Configuration for SCIM for content access

1. Log in to Okta as an admin.
2. Browse the Okta Integrations Network and search “Lucid”.
3. Create a new Lucid app.
   • If you are also using SCIM for admin management, we suggest naming this app “Lucid for content access” to differentiate the two.
4. In the General Settings section of the Lucid for content access app in Okta, select whether you would like to display "diagramming" and/or "whiteboarding".
   • If you are also using SCIM for admin management, we suggest unchecking both “diagramming” and “whiteboarding” in this app to prevent duplicate Lucid tiles for end users.
5. Under the "Provisioning" tab, click Configure API Integration.
6. Check the box next to "Enable API Integration". 
   • A text field will appear where you can add your bearer token that was generated by Lucid.
7. Paste the bearer token generated by Lucid from the SCIM for content access tile into the API token field.
   • Keep in mind that if you are setting up both Lucid SCIM apps, this is a separate bearer token from the SCIM for admin management token. Be sure to use the correct one with each app.
8. Make sure that “Import Groups” is not checked (unless you want your existing Lucid teams imported to Okta).
9. Click Save.

Set up SCIM for admin management

The groups that you set up for SCIM for admin management will be used to manage licensing and granular admin controls at scale, including attribute management (e.g. cost center, region, etc). These groups can also be used to automatically provision users and Lucid org groups to reflect company hierarchy.

Set up an All users group

Follow these steps to set up an All users group in Okta.

1. Navigate to the “Assignments” tab of the Lucid application in Okta.
2. Click Assign from the top-left of the "Assignments" page.
3. From the dropdown options, select Assign to Groups.
4. Search for your “All users” group.
   • Having an All users group (which will most likely have a different name for your company) is important as it is typically used to assign all users at your company to this Okta application. This is what enables them to sign in and see the Lucid tiles within the main Okta applications page.
5. Click Assign.

Assign license groups via group push

Group Push in Okta allows admins to provision groups from Okta as organizational groups in Lucid. These Okta push groups are used to license and delicense users in Lucid.

To create new push groups that work with Lucid organizational groups, follow these steps:

1. Select the Push Groups tab from the menu at the top of the Lucid app page in Okta.
2. Click + Push Groups.
3. From the dropdown options, select Find groups by name.
4. We recommend customizing licensing groups.
   • These groups will be used to assign a user a license in Lucid based on their membership to the group.
   • Removing users from a licensing group will delicense them to free up licenses for others to use.
5. Click Save & Add Another if you need to add another group.
6. Click Save when you’ve added your last group.

View Okta push groups as organizational groups in Lucid

At this stage of the process, we recommend double-checking you see the expected Okta push groups as organizational groups in Lucid, which confirms the SCIM group setup was successful. To access the organizational groups page in Lucid, follow these steps:

1. Navigate to the Lucid admin panel.
2. Select Groups from the left-hand navigation menu.
3. From the dropdown menu, click Organizational groups.

You can expect to see your Okta push groups as organizational groups on this page of the Lucid admin panel.

Configure license settings for each group

You’re now ready to configure the license settings for each of your organizational groups. This ensures that users are licensed or delicensed appropriately when they are added to or removed from any of these groups. 

To access license settings, follow these steps:

1. Navigate to the Lucid admin panel.
2. Select License settings from the left-hand navigation menu.
3. From the dropdown menu, click Lucid Suite settings.
4. Proceed to the appropriate set of steps below to customize license settings for each organizational group.

Configure license setting for licensing users group:

1. Select your desired licensing group from the list of organizational groups on the left-hand side of the licensing page.
2. Under the “Access eligibility” section, select Eligible for full access.
3. Under “Customized eligibility criteria”, select Instant access.
4. Click Save changes.
5. Repeat these steps for any additional licensing groups.

You have now completed all the steps to reconfigure the Lucid app. License settings will now be managed via the organizational groups created via SCIM.

Assign roles to users with SCIM

To define a user's role, you will use the strings "AccountAdmin" and "BillingAdmin." To apply both admin roles to a user, you will need to assign multiple roles to the users or groups rather than a single role with a concatenated string.

Set up SCIM for content access

SCIM for content access is ideal for managing collaboration and document sharing. It allows you to provision and deprovision users and teams directly from your identity provider, but doesn’t manage licensing. To set up a SCIM for content access app in Okta, follow the steps from the Configure SCIM for the Lucid Suite in Okta section, then return here to continue with the steps to customize your user groups.

We recommend creating these groups for sharing by department, location, etc. depending on your account needs.

Assign users under Assignments tab in Okta

1. Navigate to the “Assignments” tab of the Lucid SCIM for content access app you created in Okta.
2. Click Assign from the top-left of the Assignments page.
3. From the dropdown options, select Assign to Groups.
4. Search for the relevant Groups you will be using for sharing.
   • These could look like groups specific to your departments, locations, etc. These can align with and match the push groups you will use in the next section.
   • Alternatively, you can also use your “All users” group that you may be using for the SCIM for admin management app. Refer to the Set up an All users group section if you wish to use that.
5. Click Assign.

Add users to push groups in Okta

Group Push in Okta allows admins to push groups from Okta to Lucid and manage Lucid teams for sharing through Okta. 

To create new push groups for content access, follow these steps:

1. Select the Push Groups tab from the menu at the top of the Lucid app page in Okta.
2. Click + Push Groups.
3. From the dropdown options, select Find groups by name.
4. Add and customize the groups that you want for document sharing, which may look like groups by department, location, etc.
5. Click Save & Add Another if you need to add another group.
6. Click Save when you’ve added your last group.

Access teams from Lucid admin panel

The groups that you create will be visible in the Lucid admin panel by following these steps:

1. Navigate to the Lucid admin panel.
2. Select Groups from the left-hand navigation menu.
3. From the dropdown menu, click Teams.

FAQ

What happens to documents when I delicense a user via SCIM?

When you delicense a user via SCIM, their documents will be transferred to another user on your Enterprise account. The document transfer will occur 24 hours after delicensing via SCIM.

By default, the account owner will be the recipient of the documents that are automatically transferred upon delicensing a user. You can change the recipient of the transferred documents by navigating to the SCIM integration settings in the Lucid admin panel and selecting Modify default owner to the right-hand side of the email address. See the screenshot below for reference.

Clicking Modify default owner redirects you to the “Compliance settings” page of the admin panel where you can change who the default document owner on your account is. Refer to our Lucid admin panel: Compliance settings article for additional details.

Does JIT provisioning handle updates, deletions, and deactivations of users in Lucid?

No. JIT provisioning cannot update, delete, or deactivate a user in Lucid since it only works during a user's first login. That means any update, deletion, or deactivation would need to be done within the Lucid Admin Panel if you are not using SCIM.

If you want to update users and allow for automation of deactivating users, you should use SCIM instead of Just-In-Time provisioning.

Resources

To learn more about this feature or to ask additional questions, explore the additional resources below. These resources are available in English only.

Community post

Instructions to update IdP metadata certificate (renew SSO cert)

Give feedback on this article