# Configuring Single Sign-On (SSO)

> Loadster offers SSO with SAMLv2 with certain annual and custom plans. Setting up Single Sign-On is generally fairly straightforward.

Source: https://loadster.com/manual/sso/

Loadster offers SSO with SAML 2 with certain annual and custom plans. Please contact
[sales@loadster.com](mailto:sales@loadster.com) to check if your plan includes this or to inquire about 
a reasonably-priced add-on subscription to enable SSO for your organization.

This guide covers how to integrate Loadster with your identity provider for Single Sign-On authentication and automatic
user provisioning, when it's supported by your plan.

## SSO Overview

Loadster supports two complementary SSO technologies:

1. **SAML 2.0 Authentication** - Allows users to log in using their corporate identity provider credentials
2. **SCIM 2.0 User Provisioning** - Automatically creates and removes user access as employees join or leave your
   organization

These can be used together or independently. If you enable SAML without SCIM, user account provisioning and
updates will happen "just in time" whenever a user at your organization completes SSO authentication. Enabling SCIM
helps keep your organization's user accounts in sync even if users aren't signing in to Loadster, and can be helpful
in automatically deactivating Loadster accounts for users who leave your organization.

## SAML 2.0 Authentication Setup

SAML 2.0 enables your users to authenticate with Loadster using their existing corporate credentials from identity
providers like Microsoft Entra ID (Azure AD), Okta, Google Workspace, and others.

### Microsoft Entra ID Setup

#### Prerequisites

- Admin access to your Microsoft Entra ID (Azure AD) tenant
- Permission to create Enterprise Applications in Azure

#### Create Enterprise Application in Azure

- Sign in to the Azure Portal (https://portal.azure.com)
- Navigate to: **Entra ID** → **Enterprise Applications** → **New Application**
- Select **Create your own application**
- Name it "Loadster" (or your preferred name)
- Choose **Integrate any other application you don't find in the gallery (Non-gallery)**
- Click **Create**

#### Configure SAML Single Sign-On

- In your new application, go to **Single sign-on** and select **SAML**
- Click **Edit** on **Basic SAML Configuration** and enter the following:

  **Identifier (Entity ID):**
   ```
   https://api.loadster.com/saml2/service-provider-metadata/{REGISTRATION_ID}
   ```
  (We'll provide the exact {REGISTRATION_ID} value)

  **Reply URL (Assertion Consumer Service URL):**
   ```
   https://api.loadster.com/login/saml2/sso/{REGISTRATION_ID}
   ```
  (We'll provide the exact {REGISTRATION_ID} value)

  **Sign on URL:**
   ```
   https://api.loadster.com/saml2/authenticate/{REGISTRATION_ID}
   ```
  (We'll provide the exact {REGISTRATION_ID} value)

  **Logout URL:**
   ```
   https://api.loadster.com/logout/saml2/slo
   ```

- Click **Save**

#### Configure User Attributes & Claims

- Click **Edit** on **Attributes & Claims**
- Ensure the following claims are configured:

  | Claim Name | Source Attribute |
  |------------|------------------|
  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | user.mail |
  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | user.givenname |
  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | user.surname |
  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | user.displayname |

- Click **Save**

#### Assign Users or Groups

- Navigate to **Users and groups** in your Enterprise Application
- Click **Add user/group**
- Select the users or groups that should have access to Loadster via SSO
- Click **Assign**

#### Download Federation Metadata

- Go back to **Single sign-on** → **SAML**
- In section **3** (SAML Certificates), find **Federation Metadata XML**
- Click **Download** to save the XML file

#### Information to Provide to Loadster

Please provide us with the following:

- **Federation Metadata XML file** (downloaded in Step 5)
- **Company/Organization name** (for our records)
- **Primary contact email** (for SSO setup notifications)
- **Preferred Registration ID** (optional - we can suggest one based on your company name, e.g., "acme-corp")
- **Email domains** that should be allowed to use SSO (e.g., @yourcompany.com)
- **SSO requirement preference**:
    - **Enforce SSO** - Disable password-based login for all team members (recommended)
    - **Allow both** - Permit both SSO and password-based login

#### Next Steps

Once you've completed this checklist:

1. Email the Federation Metadata XML file and answers to the above questions to your Loadster support contact
2. We'll configure SSO on our end (typically within 1-2 business days)
3. We'll provide you with the exact URLs (with {REGISTRATION_ID} filled in) to finalize your Azure configuration

### Okta Setup

#### Prerequisites

- Admin access to your Okta organization
- Permission to create applications in Okta

#### Create Application in Okta

- Sign in to Okta Admin Console (https://your-domain.okta.com/admin)
- Navigate to: **Applications** → **Applications** → **Create App Integration**
- Select **SAML 2.0**
- Click **Next**

#### General Settings

- **App name**: Enter "Loadster" (or your preferred name)
- **App logo**: (Optional) Upload a logo
- Click **Next**

#### Configure SAML Settings

In the **SAML Settings** section, enter the following:

* **Single sign-on URL:**
   ```
   https://api.loadster.com/login/saml2/sso/{REGISTRATION_ID}
   ```
  We'll provide the exact {REGISTRATION_ID} value.

    - Check **Use this for Recipient URL and Destination URL**

* **Audience URI (SP Entity ID):**
   ```
   https://api.loadster.com/saml2/service-provider-metadata/{REGISTRATION_ID}
   ```
  We'll provide the exact {REGISTRATION_ID} value.

* **Default RelayState:** (leave blank)

* **Name ID format:** `EmailAddress`

* **Application username:** `Email`

Click **Show Advanced Settings**

*  **Response:** `Signed`
*  **Assertion Signature:** `Signed`
*  **Signature Algorithm:** `RSA-SHA256`
*  **Digest Algorithm:** `SHA256`
*  **Assertion Encryption:** `Unencrypted`

#### Attribute Statements

- In the **Attribute Statements** section, add the following mappings:

  | Name | Name format | Value |
  |------|-------------|-------|
  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | Unspecified | `user.email` |
  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | Unspecified | `user.firstName` |
  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | Unspecified | `user.lastName` |
  | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | Unspecified | `user.displayName` |

- Click **Next**

#### Feedback

- Select **I'm an Okta customer adding an internal app**
- Check **This is an internal app that we have created**
- Click **Finish**

#### Assign Users or Groups

- In your new application, go to the **Assignments** tab
- Click **Assign** → **Assign to People** or **Assign to Groups**
- Select the users or groups that should have access to Loadster
- Click **Assign** and **Done**

#### Download Metadata

- Go to the **Sign On** tab
- Scroll down to **SAML 2.0** section
- Right-click on **Identity Provider metadata** link
- Select **Save Link As...** to download the XML file

#### Information to Provide to Loadster

Please provide us with the following:

- **Identity Provider Metadata XML file** (downloaded in Step 7)
- **Company/Organization name** (for our records)
- **Primary contact email** (for SSO setup notifications)
- **Preferred Registration ID** (optional - we can suggest one based on your company name, e.g., "acme-corp")
- **Email domains** that should be allowed to use SSO (e.g., @yourcompany.com)
- **SSO requirement preference**:
    - **Enforce SSO** - Disable password-based login for all team members (recommended)
    - **Allow both** - Permit both SSO and password-based login

#### Next Steps

Once you've completed this checklist:

1. Email the Identity Provider Metadata XML file and answers to the above questions to Loadster
2. We'll configure SSO on our end (typically within 1-2 business days)
3. We'll provide you with the exact URLs (with {REGISTRATION_ID} filled in) to finalize your Okta configuration

### Google Workspace Setup

#### Prerequisites

- Super Admin access to your Google Workspace account
- Permission to create custom SAML applications

#### Access SAML Apps

- Sign in to Google Admin Console (https://admin.google.com)
- Navigate to: **Apps** → **Web and mobile apps**
- Click **Add App** → **Add custom SAML app**

#### App Details

- **App name**: Enter "Loadster" (or your preferred name)
- **Description**: (Optional) Enter a description
- **App icon**: (Optional) Upload an icon
- Click **Continue**

#### Google Identity Provider Details

- Click **Download Metadata** to save the XML file (you'll need this later)
- Click **Continue**

#### Service Provider Details

- Enter the following information:

  **ACS URL:**
   ```
   https://api.loadster.com/login/saml2/sso/{REGISTRATION_ID}
   ```
  (We'll provide the exact {REGISTRATION_ID} value)

  **Entity ID:**
   ```
   https://api.loadster.com/saml2/service-provider-metadata/{REGISTRATION_ID}
   ```
  (We'll provide the exact {REGISTRATION_ID} value)

  **Start URL:** (leave blank)

  **Signed response:** Check this box

  **Name ID format:** `EMAIL`

  **Name ID:** `Basic Information > Primary email`

- Click **Continue**

#### Attribute Mapping

- Click **Add Mapping** for each of the following:

  | Google Directory attributes | App attributes |
  |----------------------------|----------------|
  | Primary email | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` |
  | First name | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` |
  | Last name | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` |
  | Primary email | `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` |

- Click **Finish**

#### Turn On Service for Users

- Click on the newly created "Loadster" app
- Click **User access**
- Select:
    - **ON for everyone** - To enable for all users in your organization
    - **OFF for everyone, then create access for specific organizational units** - To enable for specific
      departments/groups
- Click **Save**

#### Information to Provide to Loadster

Please provide us with the following:

- **Google Identity Provider Metadata XML file** (downloaded in Step 3)
- **Company/Organization name** (for our records)
- **Primary contact email** (for SSO setup notifications)
- **Preferred Registration ID** (optional - we can suggest one based on your company name, e.g., "acme-corp")
- **Email domains** that should be allowed to use SSO (e.g., @yourcompany.com)
- **SSO requirement preference**:
    - **Enforce SSO** - Disable password-based login for all team members (recommended)
    - **Allow both** - Permit both SSO and password-based login

#### Next Steps

Once you've completed this checklist:

1. Email the Google Identity Provider Metadata XML file and answers to the above questions to your Loadster support
   contact
2. We'll configure SSO on our end (typically within 1-2 business days)
3. We'll provide you with the exact URLs (with {REGISTRATION_ID} filled in) to finalize your Google Workspace
   configuration

## SCIM 2.0 User Provisioning

SCIM (System for Cross-domain Identity Management) automatically synchronizes users between your identity provider and
Loadster. This eliminates the need to manually manage user access and ensures that employees who leave your organization
are immediately deprovisioned.

### What SCIM Provides

- **Automatic user creation** - New users are created when assigned in your IdP
- **Automatic deprovisioning** - Users are removed when unassigned or deleted in your IdP
- **Profile synchronization** - User attributes (name, email) are kept in sync
- **Just-in-time updates** - Changes propagate immediately to Loadster

### How It Works

Loadster's SCIM endpoints conform to the standard, as follows:

- `GET /scim/v2/ServiceProviderConfig` - Configuration metadata (public)
- `GET /scim/v2/Schemas` - Schema definitions (public)
- `GET /scim/v2/ResourceTypes` - Resource types (public)
- `GET /scim/v2/Users` - List users (requires auth)
- `GET /scim/v2/Users/{id}` - Get user (requires auth)
- `POST /scim/v2/Users` - Create user (requires auth)
- `PUT /scim/v2/Users/{id}` - Update user (requires auth)
- `PATCH /scim/v2/Users/{id}` - Patch user (requires auth)
- `DELETE /scim/v2/Users/{id}` - Delete user (requires auth)

### Supported Identity Providers

SCIM is an open standard (IETF RFCs 7643/7644) supported by many identity providers:

- Microsoft Entra ID (Azure AD)
- Okta
- Google Workspace
- OneLogin
- JumpCloud
- And many others

### Setting Up SCIM

#### Step 1: Request SCIM Token

Contact your Loadster support representative to request a SCIM provisioning token. This is a special authentication
token used by your identity provider to communicate with Loadster's SCIM API.

**Token characteristics**:

- Team-specific: Each token is scoped to your team
- Long-lived: Does not expire or get revoked on password changes
- Secure: High-entropy random token

#### Step 2: Configure Your Identity Provider

##### Microsoft Entra ID

1. Go to Azure Portal → Entra ID → Enterprise Applications
2. Select or create your application (same as used for SAML)
3. Navigate to **Provisioning** → **Automatic**
4. Configure:
    - **Tenant URL**: `https://api.loadster.com/scim/v2`
    - **Secret Token**: The SCIM token provided by Loadster
5. Click **Test Connection** to verify
6. Set up attribute mappings (usually defaults are fine):
    - `userName` → `userPrincipalName`
    - `name.givenName` → `givenName`
    - `name.familyName` → `surname`
    - `emails[type eq "work"].value` → `mail`
    - `active` → (leave as default)
7. Click **Save**
8. Enable provisioning by setting **Provisioning Status** to **On**
9. Click **Save** and **Start provisioning**

##### Okta

1. Go to Okta Admin → Applications
2. Select your application (same as used for SAML)
3. Navigate to **Provisioning** → **Configure API Integration**
4. Check **Enable API integration**
5. Configure:
    - **Base URL**: `https://api.loadster.com/scim/v2`
    - **API Token**: The SCIM token provided by Loadster
6. Click **Test API Credentials** to verify
7. Click **Save**
8. Enable provisioning features:
    - **To App** → **Create Users**, **Update User Attributes**, **Deactivate Users**
9. Map attributes in the **Provisioning** → **To App** settings
10. Save and assign users/groups to the application

##### Google Workspace

Note: at least some versions of Google Workspace only allow SCIM for apps officially vetted by Google.
Please check with us on the current status of this.

1. Sign in to Google Admin Console (https://admin.google.com)
2. Navigate to: **Apps** → **Web and mobile apps**
3. Select your Loadster application (same as used for SAML)
4. Click **Provisioning**
5. Click **Configure Provisioning**
6. Configure:
    - **SCIM Base URL**: `https://api.loadster.com/scim/v2`
    - **Authorization**: Select **Bearer token**
    - **Access Token**: The SCIM token provided by Loadster
7. Click **Test Connection** to verify
8. Click **Continue**
9. Enable provisioning features:
    - **Create new users** - Check this box
    - **Update existing users** - Check this box
    - **Delete users** - Check this box
10. Set up attribute mappings (usually defaults are fine):
    - `userName` → `Primary Email`
    - `name.givenName` → `First Name`
    - `name.familyName` → `Last Name`
    - `emails[type eq "work"].value` → `Primary Email`
    - `active` → (leave as default)
11. Click **Finish**
12. Click **Turn on provisioning** to enable
13. Users assigned to the Loadster app will now be automatically provisioned

**Note**: Google Workspace may take several minutes to complete the initial sync.

### Troubleshooting

#### SAML Authentication Issues

- **"Invalid SAML response"** - Verify that the Entity ID and ACS URL exactly match the values we provided
- **"User not authorized"** - Ensure the user is assigned to the application in your IdP
- **"Missing claims"** - Verify all required claims (email, givenname, surname, name) are configured

#### SCIM Provisioning Issues

- **"401 Unauthorized"** - Verify the SCIM token is correct and hasn't been revoked
- **"403 Forbidden"** - Contact Loadster support to ensure your token is properly configured for provisioning
- **"Connection failed"** - Verify the Tenant URL is `https://api.loadster.com/scim/v2` (no trailing slash)
- **Users not syncing** - Check provisioning logs in your IdP for detailed error messages

### Support

For assistance with SSO setup or other questions, please email help@loadster.com.