securiCAD Enterprise can be integrated with the single sign-on technologies OpenID Connect and SAML 2.0. We strongly recommend that you use OpenID Connect rather than SAML. See https://www.okta.com/identity-101/whats-the-difference-between-oauth-openid-connect-and-saml/ and https://developer.okta.com/code/python/pysaml2/ for more information.

In the following sections, we will describe how to integrate securiCAD Enterprise with Okta. Instructions for other identity providers might differ. In the example below, securiCAD Enterprise is assumed to be installed on a host reachable on https://192.0.2.231.

📘

Use the URL of your own host when setting up SSO in your environment. If available, use the domain name instead of the IP address.

OpenID Connect

Create a New App Integration in Okta

Choose sign-on method OIDC - OpenID Connect and application type Web Application:

Enter an app integration name, e.g. securiCAD Enterprise, optionally upload a logo, and enter the following URIs:

Manage assignments and and click "Save". On the next page, note down your Client ID, Client secret, and Okta domain:

Configure OpenID Connect in securiCAD Enterprise

Create a file /home/es/client_secrets.json with the following content:

{
  "web": {
    "client_id": "********************",
    "client_secret": "****************************************",
    "auth_uri": "https://************.okta.com/oauth2/default/v1/authorize",
    "token_uri": "https://************.okta.com/oauth2/default/v1/token",
    "issuer": "https://************.okta.com/oauth2/default",
    "userinfo_uri": "https://************.okta.com/oauth2/default/v1/userinfo",
    "audience": "api://default",
    "jwks_uri": "https://************.okta.com/oauth2/default/v1/keys",
    "redirect_uris": [
      "https://192.0.2.231/api/v1/oidc/callback"
    ]
  }
}

Replace appropriate entries with the values noted down above.

🚧

"The requested feature is not enabled in this environment"

If you receive the above error message in Okta or the error code illegal_redirect_uri. Remove /default from the URLs in client_secrets.json

Finally configure OpenID Connect by editing the sso section in /home/es/bin/enterprise_suite/backend/apps/es/configs/config.json:

{
  ...
  "sso": {
    "oidc": {
      "enabled": true,
      "client_secrets_path": "/home/es/client_secrets.json",
      "auto_create_users": true,
      "auto_create_organizations": true
    },
    ...
    "organization": "default_sso_org",
    "redirect_url": "https://192.0.2.231/auth"
  },
  ...
}

Restart the backend for the settings to take effect:

sudo systemctl restart foreseeti-backend

Sign in With OpenID Connect

Once OpenID Connect has been configured, a new button "Login with SSO" will appear:

Clicking the button will take you to Okta:

Entering your credentials and clicking "Sign In" will sign you in to securiCAD Enterprise:

If this is the first time you log in, a user will automatically be created in with user privileges. A system admin or an organization admin can later change your privileges as needed.

Multi-tenancy using OIDC

Single Sign-On can be used on a multi-tenant system using OIDC. This requires some additional configuration on your Identity provider:

1. securiCAD Enterprise application must have access to read user claim groups via userinfo API.
2. securiCAD Enterprise users are assigned to groups with the following name convention:

foreseeti-<role>-<organization>

Role needs to be one of following securiCAD Enterprise roles:

• user
• project_creator
• admin

Make groups claim available in userinfo API using Okta

To allow securiCAD Enterprise application to read groups claim via userinfo API, go to Security > API and edit the API used by the securiCAD Enterprise application. Then go to Claims tab and add a new claim. Type groups as name, select ID token and Userinfo / id_token request as token type, select Groups as value type. For filter, select Matches regex and type .* as value. Lastly select Any scope and click Create. You are now set up for Single Sign-On with Multi-tenancy.

Once a user is authenticated, the user is asked to select the organization the user wish to log into. Each group with the above name convention the user is assigned to will be available to the user along with the default SSO organization in securiCAD Enterprise.

SAML 2.0

Create a New App Integration in Okta

Choose sign-on method SAML 2.0:

Enter an app name, e.g. securiCAD Enterprise, optionally upload a logo, choose an IdP name, e.g. es.okta.com, and enter the following URIs:

Enter the following attribute statements:

Manage assignments and download the metadata file and save it as es.okta.com.metadata:

Configure SAML 2.0 in securiCAD Enterprise

Copy the metadata file to /home/es/es.okta.com.metadata.

Finally configure SAML 2.0 by editing the sso section in /home/es/bin/enterprise_suite/backend/apps/es/configs/config.json:

{
  ...
  "sso": {
    ...
    "saml": {
      "enabled": true,
      "idp_name": "es.okta.com",
      "entity_id": "https://192.0.2.231/api/v1/saml/sso/es.okta.com",
      "metadata_path": "/home/es/es.okta.com.metadata"
    },
    "organization": "default_sso_org",
    "redirect_url": "https://192.0.2.231/auth"
  },
  ...
}

Restart the backend for the settings to take effect:

sudo systemctl restart foreseeti-backend

Sign in With SAML 2.0

Once SAML 2.0 has been configured, a new button "Login with SSO" will appear:

Clicking the button will take you to Okta:

Entering your credentials and clicking "Sign In" will sign you in to securiCAD Enterprise:

If this is the first time you log in, a user will automatically be created in with user privileges. A system admin or an organization admin can later change your privileges as needed.