Configure and Enable OpenID Connect

This page describes how you can use OpenID Connect (OIDC) to manage user access to your organization. Diligent will need to enable the feature and you will need to configure changes in your Secure File Sharing organization on the OIDC server before you can use it.

OIDC servers require Secure File Sharing to be registered as a new client for authentication. This involves the following activities:

  1. Create a pair of Client ID and Client Secret

  2. Specify the redirect URL

    Client ID and Client Secret are required for the next step, Configure OIDC in Secure File Sharing.

    The redirect URL can only be specified after you have configured OIDC in your Secure File Sharing organization. For the individual steps regarding the redirect URL, go to Complete OpenID Connect server configuration

Configure OpenID Connect

Only an Organization Administrator can undertake this activity from their administration profile.

  1. Select the Identity tab to open the OpenID Connect dialog.

  2. Select Edit next to the Provider selection and Custom from the menu.

    Note

    You may need to contact the person responsible for your OIDC provider for information. The Provider list also contains several preset configurations.

  3. In the Server URL field enter the OIDC server URL. Example: https://mycompany.okta.com

  4. In the Client ID field enter a valid OIDC server OAuth 2.0 Client Identifier.

  5. In the Client Secret field enter the secret that is used to authenticate Secure File Sharing with the OIDC Server.

    Note

    Secure File Sharing requires Client ID and Client Secret to authenticate itself with the OIDC server. Authentication is required during the OAuth 2.0 dance when Secure File Sharing exchanges the authorization code for an access token. Usually, Client ID and Client Secret need to be created in the OIDC server first before the data can be entered here in this configuration. See the documentation of your OIDC server on how to configure it

  6. In the Authentication URL field, enter the OAuth 2.0 Authorization Endpoint URL. This field should match the authorization_endpoint field in the OpenID provider metadata. Example: https://mycompany.okta.com/oauth2/default/v1/authorize

  7. In Token URL, enter the OAuth 2.0 Token Endpoint URL. This field should match the token_endpoint field in the OpenID provider metadata. Example: https://mycompany.okta.com/oauth2/default/v1/token

  8. In Activated domains or users, enter the email addresses or the domain suffixes of the users that will use OIDC for sign-in.

    Note

    If you define more than one domain or user, separate the entries with a comma.

  9. Leave the Groups field empty.

  10. In Scopes, enter a comma-separated list of the OAuth 2.0 scope values. The values are added as URL parameter &scope=… to the sign-in URL (This is an external identity provider, where they can sign in to Secure File Sharing). To request support for refreshing tokens, add scope offline_access. To request support for publishing books to DiligentBoards (only supported by Diligent identity providers), add scope unity_service.manage_books. Example: openid ,profile ,email. This is the default value.

  11. Enter an ACR (Authentication Context Class Reference) claim that is added as-is to the sign-in URL as request parameter &acr_values=…. This value is optional. Example: phr

    Note

    The Diligent identity provider supports a proprietary ACR claim tenant:<site> that enables Secure File Sharing to pass the Diligent Boards site as part of the sign-in URL.

  12. Select Prefill email address on sign-in screen of identity provider. If this option is enabled, the email address of the user is added as request parameter &login_hint=… to the sign-in URL.

    Note

    This parameter is only used for users signing in via the Secure File Sharing sign-in page. The email address of the user is filled in automatically on the sign-in page of the provider of the original user account.

  13. In the Request parameter supported list, select an option for the support of the request parameter by the OIDC server.

    • Auto: Tries to auto-detect support by looking at field request_parameter_supported in document /.well-known/openid-configuration on the OIDC server.

    • On: Forces encryption of the authentication request into parameter &request= of the sign-in URL.

    • Off: Parameter &request= is not added to the sign-in URL even though the OIDC server may support it.

    Note

    The value of parameter &request… is encrypted using the encryption algorithm that is defined by the value of the Content encryption field. The encryption key is the first key matching usage “enc” that is listed in the JSON Web Key Set of the OIDC server (referenced by jwsk_uri in the OpenID provider metadata). If no encryption key is found and option Auto is enabled, then the encryption key is generated from the value of the Client Secret field using HMAC-SHA256. Make sure the value of the Client Secret field is long enough to make brute-forcing infeasible. For more information go to chapter 10.2. Encryption in the OIDC Corespecification.

  14. In the Content encryption field, define the encryption algorithm that is to be used to encrypt the &request= parameters in the sign-in URL.

    Note

    The value in this field is not used if Request parameter supported function is set to Off. Default value: A128CBC-HS256.

  15. Under CLAIMS MAPPING, you can map custom claims returned by an OIDC server to the standard claims that are understood by Secure File Sharing.

    Note

    In most cases, you won't need to set these values. However, if you want to use a Diligent identity provider, map the custom Claim ix-email that is returned by the Diligent OIDC server to the standard Claim email that is understood by Secure File Sharing. If the email Claim is missing, the sign-in fails with the error Email address is missing.

  16. Select Save to store the settings.

  17. Check whether the function is activated. To activate it, move the toggle switch from Deactivated to Activated. The sign-in URL is displayed to the right of the OpenID Connect dialog.

  18. Copy the sign-in URL to a text editor.

    You need the sign-in URL to complement the OIDC server configuration. You also need it for provisioning users to the organization.