SSO/SAML configuration with Okta Identity

This topic explains how to configure the Boards application in Okta, enabling users to access their Boards site via single sign-on (SSO).

How it works

SSO is a convenient and secure method to access all your company resources using one set of credentials. Ensuring the right person has access to the right resources requires:

An identity provider (IdP), such as Okta, responsible for user authentication.
A service provider (SP), that controls access to resources, including Boards.

Diligent supports IdP and SP initiated identity processes. Note that for IdP there is an optional extra step in the configuration process for administrators. See the Adding attributes for IdP-Initiated sign in section for more information.

Configuring Boards to your Okta tenant may require collaboration between a Boards administrator and an IT specialist who manages the IdP at your organization. This can be the same person, but typically it is different people.

Permissions requirements

The IT specialist who manages the IdP at your company needs developer access to Okta. They do not require a Boards account.

If you are collaborating with a Boards administrator, we recommend that they have access to the Site Management hub, so they can view the list of active users, their permissions, and roles.

Configuring the Diligent Boards application for SSO

Configuring SSO for Boards requires you to set up the application in Okta. First, create the Boards application. Next, obtain the signing certificate with your IdP metadata and send it to the Customer Success/Implementation team for validation. Finally, assign users to the Boards app, so they can access their account via SSO.

Creating the Diligent Boards application

This section explains how to create a new Boardsapplication in your Okta tenant and set up SSO compatibility.

Sign in to your Okta tenant.
Select Applications from the left-hand menu. A dropdown menu appears.
Select Applications from the dropdown menu.
Select Create App Integration.
The sign-in method for Boards is SAML 2.0. Select the radio button next to SAML 2.0, and then select Next.
Enter a name for the application in the App name field, such as Diligent Boards.
Select the Upload new icon in the App logo field to upload Diligent's logo.
You are not required to select an option in the App visibility field. Select Next to proceed with configuring the required SSO settings.

Setting up SSO compatibility

For SSO compatibility, Diligent requires data from your authentication provider, and it needs information from us.

Enter the following text in each field within the SAML Settings section:

Field name	Entry text
Single sign-on URL	https://identity-"environment".diligentcloudservices.com/saml/external-callback/"environment"_"site-name"
Audience URI (SP Entity ID)	https://diligent-identity/"environment"_"site-name"
Default RelayState	blank
Name ID format	EmailAddress

Note

The environment and site-name values in the above URLs are unique to your company. Contact your Diligent Customer Success/Implementation team for assistance with the URLs.

Move down the page to select Next.
Select the radio button next to I'm an Okta customer adding an internal app, and then select Finish.

Obtaining your signing certificate

This section explains how to view your IdP metadata and send it to Boards for validation.

Select Applications from the left-hand menu.
Select the Diligent Boards application.
Select the Sign On tab.
Move down the page to view the SAML Signing Certificates section.
Select Actions on the far-right of the 'SHA-1' row. A dropdown menu appears.
Select View IdP metadata from the dropdown menu. The XML file opens on a new tab in your web browser.
Download the XML file with your metadata and send it to your Diligent Customer Success/ Implementation team.

Assigning user accounts

This section describes how to assign a user to the Boards application so they can access their account via SSO.

Select Applications from the left-hand menu.
Select the Diligent Boards application.
Select the Assignments tab.
Select the Assign dropdown menu, and then select Assign to People.
Use the Search field to search for users. You can search by the user's name.
Select Assign on the far-right of a user's row to assign them to the Boards application. If the user is assigned to another application in your Okta tenant, a window appears to confirm their credentials.
Review the user's credentials, and then select Save and Go Back. You can also edit the text if needed.
Once complete, select Done.

Adding attributes for IdP-initiated sign in

Once your site is configured in Okta, you can create a new attribute to designate how users with the admin role will access the application. By default, users are directed to Boards Web Director if this attribute is not present.

Select Directory from the left-hand menu. A dropdown menu appears.
Select Profile Editor from the dropdown menu.
Select the Diligent Boards application.
Select Add Attribute.
Enter "diligent_client_id" in the Display name field.
Enter "diligent_client_id" in the Variable name field.
Move down the page to select Save.
Select Mappings.
To ensure the new attribute is correctly populated on the user group membership, select Okta User to Diligent Boards.
Enter the following expression in the Choose an attribute or enter an expression field: isMemberOfGroupName('ADMIN_GROUP_NAME') ? 'bw_book_admin' : 'bw_director'

Note

The expression language will update based on the syntax of your Okta tenant. For more information, see Okta Expression Language overview.

Note

The MemberOfGroupName value ('ADMIN_GROUP_NAME') is unique to your company. Contact your Diligent Customer Success/Implementation team for assistance with the value.
Select Save Mappings. The custom attribute will be configured within the Boards application.