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.
note

During the setup phase, users will retain access to Suger via other login methods (e.g., Google SSO) until the full switch to Okta SSO is complete. This also provides a fallback access method if SSO encounters issues.

Configuration Steps​

The configuration is a four-step process. SSO and SCIM can be set up entirely through self-service in the Suger Console.

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: Configure SSO Connection​

Configure your Okta SSO connection through our self-service setup:

  1. Navigate to Settings > SSO in Suger Console
  2. Click "Set up SSO"
  3. The system will generate a secure 24-hour setup ticket and redirect you to the Auth0 configuration wizard
  4. Follow the wizard prompts to connect your Okta Identity Provider using the credentials you collected in Step 1
  5. The connection will be active immediately upon completion
tip

If you only need SSO authentication, you can stop here. Your Okta SSO is ready to use. User management will be handled manually in the Suger Console.

If you need SCIM user provisioning for automated user lifecycle management (create, update, deactivate users), continue to Step 3 to configure SCIM directly from the Suger Console.

info

SCIM provisioning provides automated user creation, updates, deactivation, and role mapping. This is optional and only needed if you want full user lifecycle automation.

Step 3: Configure SCIM Provisioning (Optional)​

note

This step is only required if you need SCIM user provisioning. If you only configured SSO in Step 2, you can skip this section.

You can generate the SCIM credentials directly from the Suger Console:

  1. Navigate to the SCIM Configuration: In the Suger Console, go to Settings > SSO. Find your SSO connection and click the SCIM dropdown to expand the SCIM provisioning section.

  2. Generate a SCIM API Token: Click "+ Generate New Token". A dialog will appear with your token.

    warning

    Copy and save your SCIM API Token immediately. Suger does not store this token — you will not be able to view it again. If you lose it, you can delete the token and generate a new one.

  3. Copy the SCIM Credentials: After the token is generated, the following information will be available in the SCIM section. Copy them for use in Okta:

    • Organization ID
    • SCIM Endpoint URL
    • SCIM API Token (from the previous step)

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 Suger app in Okta, navigate to the Provisioning tab → To App section.
      • Find the sugerRole attribute and 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 in Okta (Required for SCIM Only)​

note

This step is only required if you configured SCIM provisioning in Step 3. If you only configured SSO, users can log in directly after the SSO connection is active. User management will be handled in the Suger Console.

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.

  7. "400 Bad Request" error during login

    • This error typically indicates a mismatch in the OIDC client credentials. Double-check that the Client ID and Client Secret you generated in Okta (Step 1) were correctly sent to and configured by Suger Support.

  8. "JIT user provisioning is disabled" error during login

    • In Okta, navigate to the Assignments tab of the Suger app.
    • Look for a red icon next to the user, which indicates a provisioning failure.
    • Try to resolve the issue by removing and re-assigning the user to the application.
    • If the error persists, contact Suger Support for assistance.

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