# Okta SSO
Manage users with Okta OIDC SSO + SCIM provisioning.
---
:::info
Fours was formerly named Suger. In Okta, the app — its Okta Integration Network listing, app label, app user profile and **Suger Organization ID** setting — still uses the name Suger until the app is renamed.
:::
## Overview
Fours 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 Fours 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 Fours)
- Identity Provider (IdP)-Initiated SSO (logging in from Okta)
- **SCIM Provisioning:**
- **Create Users:** Automatically provision Okta users in Fours.
- **Update User Attributes:** Sync user profile changes (e.g., role).
- **Deactivate Users:** Automatically deactivate Fours users when they are unassigned in Okta.
:::note
Users will retain access to Fours via other login methods (e.g., Google SSO or username/password) even after Okta SSO is configured — Fours does not currently block these as long as they exist for the user. This is useful as a fallback if SSO has an issue, but it has one important consequence: **`sugerRole` updates pushed via SCIM only take effect the next time the user signs in through the Okta connection.** If a user keeps signing in via Google or username/password instead, their role changes from Okta will never be applied, with no error shown. To require Okta for every sign-in to your organization, contact [Fours Support](mailto:support@suger.io); Fours turns this on for you, and it is not a self-service setting. Once it is on, password, Google and Microsoft sign-in stop working for your organization's users, and any sign-in (including **Continue with Google**) takes them to Okta.
:::
---
## Configuration Steps
The configuration is a four-step process. SSO and SCIM can be set up entirely through self-service in the Fours 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" (Fours' former name) and add it.
- Alternatively, visit the [Suger OIN App page](https://www.okta.com/integrations/suger/) directly.
> 
2. **Enter Placeholder Values**: On the "General Settings" screen, enter the following temporary values. These will be replaced with real values provided by Fours Support later.
- **Suger Organization ID**: `SugerOrg` (This is a fake organization ID. It will be updated to the your real Fours organization ID later)
- **SCIM endpoint URL**: `https://www.fours.com/`
- 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 Fours 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
> 
:::note
**You can ignore the "Callback URL" field shown in the wizard.** Because you are using the Suger app from the Okta Integration Network (OIN), the callback URL is already pre-configured by Fours — no manual setup is required.
:::
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
:::warning
If you already synced your partner portal's sign-in form (**Settings > Partner > Login Page > Sync to Auth0**), setting up SSO turns off Google, Microsoft, and email-and-password sign-in on that branded form the next time **Settings > SSO** loads, so that form then offers your partners only your organization's own SSO sign-in. If SSO is already set up when you sync, the sync never turns those sign-in methods on. See [Brand the sign-in form](/prm/partner-portal-login-page/#brand-the-sign-in-form-optional).
:::
:::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 Fours 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 Fours 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 Fours Console:
1. **Navigate to the SCIM Configuration**: In the Fours 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.** Fours 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 Fours 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 Fours 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 Fours 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 Fours Console.
:::
Instead of assigning roles to individual users, the best practice is to assign users to Okta groups that correspond to Fours 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 Fours 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 stop offering Google or username/password sign-in altogether, see the note at the top of this page.)
> 
### Note
:::warning
Once this integration is active, all user management (creation, deactivation, and role changes) **MUST** be done in Okta. Manual changes in the Fours 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 Fours console under Settings > Organization. Ensure the Okta connection name is correct and does not contain any extra characters such as spaces.
3. **User provisioning**
- SCIM provisioning a user (via Okta) only creates their identity ahead of time — it does **not** immediately create a visible Fours account.
- The user will not appear in the Fours console, and will not have a role assigned, until they complete their first login via Okta SSO. Okta reporting "Success" for a push/sync does not mean the user is visible in Fours yet.
4. **SCIM provisioning for `sugerRole` updates**
- To apply `sugerRole` updates, log out and then log back into the Fours 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 Fours console.
6. **User deprovisioning**
- After a user is un-provisioned, they will lose access to the Fours console upon their next login attempt. However, they can continue accessing the Fours console until their current session expires.
- The user will still be visible in the Fours 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 Fours 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 Fours Support for assistance.
9. **MFA prompt appears even though Okta already enforces MFA**
- Fours currently enforces its own MFA independent of your identity provider's MFA policy. There is no setting yet to disable Fours' MFA when SSO/Okta MFA is already in place — if this double-prompting is a problem for your users, contact Fours Support to flag it as a feature request.
If you have any further questions, please contact Fours support at [support@suger.io](mailto:support@suger.io).