Skip to main content

Okta SSO

Manage users with Okta OIDC SSO + SCIM provisioning.

Overview​

Suger is available on the Okta Integration Network (OIN), offering robust support for both OIDC Single Sign-On (SSO) and user provisioning via SCIM (System for Cross-domain Identity Management). By integrating Suger with Okta, you can centralize user authentication and streamline user management across your organization.

This guide will walk you through configuring OIDC SSO for effortless, secure logins and setting up SCIM provisioning to automate user lifecycle management—all directly from your Okta environment.

Supported Features:

  • OIDC SSO:
    • Service Provider (SP)-Initiated SSO (logging in from Suger)
    • Identity Provider (IdP)-Initiated SSO (logging in from Okta)
  • SCIM Provisioning:
    • Create Users: Automatically provision Okta users in Suger.
    • Update User Attributes: Sync user profile changes (e.g., role).
    • Deactivate Users: Automatically deactivate Suger users when they are unassigned in Okta.

Configuration Steps​

The configuration is a four-step process involving information exchange between you and Suger Support.

info

Prerequisites: You must have administrative access to your organization's Okta account.

Step 1: Initial Okta Setup & Information Gathering​

First, add the Suger application from the Okta Integration Network (OIN) and enter temporary placeholder values.

  1. Add the Suger App:

    • In your Okta Admin Console, navigate to Applications → Browse App Catalog, search for "Suger" and add it.
    • Alternatively, visit the Suger OIN App page directly.

  2. Enter Placeholder Values: On the "General Settings" screen, enter the following temporary values. These will be replaced with real values provided by Suger Support later.

    • Suger Organization ID: SugerOrg (This is a fake organization ID. It will be updated to the your real Suger organization ID later)
    • SCIM endpoint URL: https://www.suger.io/
    • Click Done.

  3. Collect OIDC Credentials:

    • Open the Suger app in Okta and navigate to the Sign On tab.
    • Copy the Client ID and Client Secret.
    • Note your Okta Domain (e.g., dev-12345678.okta.com).

Step 2: Send Credentials to Suger Support​

Send the following three items to Suger Support:

  1. Client ID
  2. Client Secret
  3. Okta Domain

Suger Support will use this information to configure the connection on the backend. Please pause here and wait for a response from our support team before proceeding.

Step 3: Finalize Okta Configuration​

Suger Support will reply with the following information:

  1. Suger Organization ID
  2. SCIM Endpoint URL
  3. SCIM API Token

Use these values to complete the setup in Okta.

A. Update General Settings​

  1. In the Suger app in Okta, navigate to the General tab and click Edit in the "App Settings" section.
  2. Replace the placeholder values with the Suger Organization ID and SCIM Endpoint URL provided by Suger Support.
warning
  • Ensure the SCIM endpoint URL ends with a trailing slash (/).
  • Ensure the Suger Organization ID has no leading or trailing spaces.

B. Configure SCIM Provisioning​

  1. Enable API Integration:

    • Navigate to the Provisioning tab and click Configure API Integration.
    • Check Enable API Integration.
    • Paste the SCIM API Token provided by Suger Support into the "API Token" field.
    • Click Test API Credentials. A success message should appear.
    • Click Save.

  2. Enable Provisioning Features:

    • In the "Provisioning to App" section, click Edit.
    • Enable Create Users, Update User Attributes, and Deactivate Users.
    • Click Save.

  3. Map User Roles: To manage user roles (Admin, Editor, Viewer) in Suger via Okta, you must create a custom attribute and map it.

    • Create a Custom Attribute on the Okta User Profile:

      • Go to Directory → Profile Editor → Okta → User (default) profile and click Edit.
      • Add a new attribute with the following settings:
        • Data type: string
        • Display name: Suger Role
        • Variable name: sugerRole
        • Check Define enumerated list of values and add the following members:
          • ADMIN
          • EDITOR
          • VIEWER
        • Default value: VIEWER
        • Click Save.

    • Create a Custom Attribute on the Suger App User Profile:

      • Go to Directory → Profile Editor → Apps → Suger App user profile and click Edit.
      • Add a new attribute with the following settings:
        • Data type: string
        • Display name: Suger Role
        • Variable name: sugerRole
        • External name: roles.^[type=='SUGER_ROLE'].value
        • External namespace: urn:ietf:params:scim:schemas:core:2.0:User
        • Enum: Define enumerated list of values
        • Attribute members: ADMIN, EDITOR, VIEWER
        • Attribute required: Yes
        • Attribute type: Group
        • Click Save.

    • Map the Attribute to the Suger App:

      • In the Profile Editor, find the Suger App user profile and click Edit.
      • In the attributes list, find sugerRole and click its edit icon.
      • Set the mapping:
        • Attribute value: Map from Okta Profile
        • Select sugerRole from the dropdown.
        • Apply on: Create and update
      • Click Save.

Step 4: Assign Users and Manage Access​

Instead of assigning roles to individual users, the best practice is to assign users to Okta groups that correspond to Suger roles.

  1. Create Okta Groups: Create three Okta groups, one for each role: Suger Admins, Suger Editors, and Suger Viewers.

  2. Assign Groups to the Suger App:

    • Navigate to the Assignments tab of the Suger app.
    • Assign each of the three groups to the application.
    • When assigning each group, override the Suger Role attribute to the corresponding value (ADMIN, EDITOR, or VIEWER).

  3. Manage Users:

    • To grant a user access, add them to one of the Suger role groups in Okta.
    • To revoke access, remove the user from the group.
    • The Suger app will now appear on the Okta dashboard for assigned users.

Using the SSO Connection​

  • Identity Provider (IdP)-Initiated: Click the Suger app icon from the Okta end-user dashboard.

  • Service Provider (SP)-Initiated:

    • Navigate to https://console.suger.io/login?orgId={your_suger_org_id}. After the first login, a shortcut will appear on the main login page https://console.suger.io/login and you can omit the orgId parameter.

    • Click "Continue with Okta" to authenticate with your Okta credentials. (Note: This step is automatically skipped if Okta is configured as the default SSO connection. To enforce Okta-only login, contact Suger Support.)

Note​

warning

Once this integration is active, all user management (creation, deactivation, and role changes) MUST be done in Okta. Manual changes in the Suger console will be overridden by Okta.

Troubleshooting​

  1. "Conflict" or "Matching user not found" error

    • If you encounter this error when assigning users to the SCIM app, navigate to Dashboard > Tasks to check the error details and retry the task.
    • If the error persists, verify the SCIM endpoint URL and API token. Ensure the SCIM endpoint URL ends with a /.

  2. "The connection is not enabled" error

    • Check the "Auth0 Enterprise Connection Name" setting in the Suger console under Settings > Organization. Ensure the Okta connection name is correct and does not contain any extra characters such as spaces.

  3. User provisioning

    • After a user is provisioned, they will gain access to the Suger console immediately.
    • The user will not be visible in the Suger console until they complete their first login via OIDC authentication.

  4. SCIM provisioning for sugerRole updates

    • To apply sugerRole updates, log out and then log back into the Suger console.
    • Updates to sugerRole may take a few minutes to reflect due to caching. Please wait a while and try again.

  5. Synced user attributes

    • Only email and sugerRole are synchronized.
    • Changes to the family name and given name will NOT be reflected in the Suger console.

  6. User deprovisioning

    • After a user is un-provisioned, they will lose access to the Suger console upon their next login attempt. However, they can continue accessing the Suger console until their current session expires.
    • The user will still be visible in the Suger console, and removal may take up to 24 hours.

If you have any further questions, please contact Suger support at support@suger.io.