How do we set up Langdock with SAML SSO and SCIM provisioning (Okta or Microsoft Entra ID)?

Implementing SAML SSO and SCIM provisioning for Langdock with Okta or Microsoft Entra ID gives you secure, centralized user management and automated onboarding/offboarding. This guide walks through the full setup: prerequisites, configuration in Langdock, and detailed steps for both identity providers.

Note: Exact menu names and screenshots may vary slightly depending on your Okta or Microsoft Entra ID tenant and UI version, but the overall flow remains the same.

---

1. Prerequisites

Before you start, ensure you have:

• Langdock
  • Admin access to your Langdock workspace
  • Langdock SSO + SCIM features enabled for your plan (contact Langdock support if unsure)
• Your Identity Provider (IdP)
  • Admin access in Okta or Microsoft Entra ID (formerly Azure AD)
  • Permission to:
    • Create SAML applications
    • Configure SSO
    • Enable SCIM provisioning or enterprise app provisioning
• General
  • A domain for your organization (for example: company.com)
  • A browser session where you can access both Langdock and your IdP

---

2. Key Concepts: SAML SSO and SCIM

Understanding what you’re setting up helps avoid misconfigurations:

• SAML SSO (Security Assertion Markup Language Single Sign-On)

  • Users authenticate via your IdP (Okta/Entra)
  • Langdock trusts your IdP and accepts SAML assertions to log users in
  • Benefits: centralized login, MFA enforcement, conditional access

• SCIM (System for Cross-domain Identity Management)

  • Automates user and group management
  • Your IdP creates, updates, and deactivates Langdock accounts
  • Benefits: automatic provisioning, deprovisioning, role assignment based on groups

You can enable SAML SSO alone, or SAML + SCIM provisioning together for full lifecycle management.

---

3. Where to Configure SAML and SCIM in Langdock

The exact navigation may vary, but typically you’ll find these settings in:

• Settings → Security / Authentication → SAML SSO
• Settings → Security / Provisioning → SCIM

Look for fields similar to:

SAML SSO settings in Langdock:

• Entity ID (a.k.a. Audience URI / SP Entity ID)
• ACS URL (Assertion Consumer Service URL / Single Sign-On URL)
• Default Relay State (optional)
• X.509 certificate (copy from IdP)
• SSO login URL / IdP SAML endpoint
• Attribute mappings (e.g., email, first_name, last_name, groups)

SCIM settings in Langdock:

• SCIM Base URL or SCIM Endpoint (e.g. https://api.langdock.com/scim/v2)
• SCIM Bearer Token or Provisioning API Token
• Supported operations: Create / Update / Deactivate users, sync groups (if enabled)

You’ll copy values between Langdock and your IdP as you configure both sides.

---

4. SAML SSO with Okta

4.1 Create a SAML 2.0 App in Okta

1. Sign in to Okta Admin Console.
2. Go to Applications → Applications.
3. Click Create App Integration.
4. Choose:
   • Sign-in method: SAML 2.0
   • Click Next.
5. Name the app, e.g. Langdock SAML SSO.
6. (Optional) Upload the Langdock logo for easier recognition.

4.2 Configure SAML Settings in Okta

In the SAML Settings screen:

1. Single sign on URL (ACS URL)

   • Paste the ACS URL from Langdock (e.g., https://app.langdock.com/saml/acs).
   • Check Use this for Recipient URL and Destination URL, if shown.

2. Audience URI (SP Entity ID)

   • Paste the Entity ID from Langdock (e.g., https://app.langdock.com/saml/metadata or a Langdock-specific string).

3. Name ID format

   • Typically: EmailAddress or Unspecified
   • Application username: set to Email (recommended) or your preferred mapping.

4. Attribute Statements (Optional but recommended)
   Add mappings such as:

   Name	Name format	Value
   email	Unspecified	user.email
   first_name	Unspecified	user.firstName
   last_name	Unspecified	user.lastName
   groups	Unspecified	String.join(",", user.groups) (or built-in groups expression)

   Check Langdock’s SAML docs for the exact attribute names it expects (for example, given_name instead of first_name).

5. Click Next, then choose I’m an Okta customer adding an internal app and finish.

4.3 Download Okta SAML Metadata

1. In the new app, go to the Sign On tab.
2. Find SAML 2.0 section and click View SAML setup instructions or Metadata.
3. Either:
   • Download the metadata XML; or
   • Copy:
     • Identity Provider Single Sign-On URL
     • Issuer (IdP Entity ID)
     • X.509 Certificate

You’ll use these in Langdock.

4.4 Configure Okta Details in Langdock

In Langdock SAML SSO settings:

1. IdP SSO URL: paste the Okta Single Sign-On URL.
2. IdP Entity ID / Issuer: paste Okta’s Issuer.
3. X.509 Certificate: paste the certificate from Okta.
4. Confirm:
   • Entity ID and ACS URL match what you entered in Okta.
5. Save the configuration.

Optionally, enable:

• Enforce SSO for all users (after you verify it works).
• Just-in-time (JIT) provisioning if supported (users created on first login).

4.5 Assign Users and Groups in Okta

1. In Okta, open the Langdock SAML SSO app.
2. Go to the Assignments tab.
3. Add:
   • People (individual users), and/or
   • Groups (recommended for easier management).
4. Only assigned users/groups will be able to sign in to Langdock via SAML.

4.6 Test SAML SSO with Okta

1. From Okta, click Applications → Langdock SAML SSO → Sign On → Test.
2. Or, log in as a user and click the Langdock tile on the Okta dashboard.
3. Alternatively, go to your Langdock SSO login URL (for example, https://app.langdock.com/sso/company).

If you see the Langdock workspace with your account created and logged in, SAML SSO is working.

---

5. SCIM Provisioning with Okta

5.1 Enable SCIM in Langdock

1. In Langdock, go to Settings → SCIM / Provisioning.
2. Enable SCIM.
3. Copy:
   • SCIM Base URL (e.g., https://api.langdock.com/scim/v2)
   • SCIM Bearer Token / API Token
4. Store the token securely; you’ll paste it into Okta.

5.2 Configure SCIM in Okta

1. In Okta Admin, open your Langdock SAML SSO app.
2. Go to the Provisioning tab.
3. Click Configure API Integration.
4. Check Enable API Integration.
5. Enter:
   • Base URL: Langdock SCIM base URL.
   • API Token: Langdock SCIM token.
6. Click Test API Credentials and confirm success.
7. Save.

5.3 Define Provisioning Settings in Okta

Still in the Provisioning tab:

1. Under Settings → To App, click Edit.

2. Enable:

   • Create Users
   • Update User Attributes
   • Deactivate Users

3. Map attributes (Okta → Langdock). Common mappings:

   • userName → user’s email
   • name.givenName → first name
   • name.familyName → last name
   • active → user active status

   Adjust as needed based on Langdock’s SCIM schema.

4. Save changes.

5.4 Assign Users and Groups for Provisioning

1. In the Assignments tab, assign users or groups to the Langdock app (if you haven’t already).
2. Okta will:
   • Provision new users in Langdock
   • Update existing users when attributes change
   • Deactivate users when they’re unassigned or deactivated in Okta

5.5 Test SCIM Provisioning with Okta

1. In Okta, choose a test user that’s assigned to the Langdock app.
2. Trigger a Provision User or update an attribute (e.g., last name) and Save.
3. Check Langdock:
   • User should be created or updated automatically.
4. Deactivate or unassign the user from the Langdock app in Okta and verify they’re deactivated in Langdock (not deleted, typically).

---

6. SAML SSO with Microsoft Entra ID (Azure AD)

6.1 Create an Enterprise Application

1. Go to Microsoft Entra admin center: https://entra.microsoft.com.
2. Navigate to Applications → Enterprise applications.
3. Click New application.
4. Choose:
   • Create your own application
   • Name it, e.g. Langdock SAML SSO.
   • Select Integrate any other application you don’t find in the gallery (Non-gallery).
5. Click Create.

6.2 Configure SAML-based Sign-on

1. Open the new Langdock SAML SSO enterprise app.
2. Under Manage, click Single sign-on.
3. Choose SAML as the sign-on method.

In the Basic SAML Configuration section:

1. Click Edit.
2. Set:
   • Identifier (Entity ID): Langdock Entity ID.
   • Reply URL (ACS URL): Langdock ACS URL.
3. Optionally:
   • Sign-on URL: Langdock login URL (if applicable).
4. Save.

6.3 Configure User Attributes and Claims

By default, Entra sends a NameID and some claims. Customize if needed:

1. In User Attributes & Claims, click Edit.

2. Ensure:

   • Name ID (Unique User Identifier) is set to user.userprincipalname or user.mail (email recommended).

3. Add claims if Langdock expects them:

   Name	Source attribute
   email	user.mail
   first_name	user.givenname
   last_name	user.surname
   groups	user.assignedroles or group claims (if you enable group claims)

4. Save.

6.4 Expose IdP Metadata from Entra

In the SAML configuration page:

1. Download the Federation Metadata XML; or
2. Copy:
   • Login URL (SAML SSO endpoint)
   • Azure AD Identifier (IdP Entity ID)
   • Certificate (Base64)

You’ll use these in Langdock.

6.5 Configure Entra SAML Details in Langdock

In Langdock SAML SSO settings:

1. IdP SSO URL: paste Entra Login URL.
2. IdP Entity ID: paste Azure AD Identifier.
3. X.509 Certificate: paste the certificate from Entra.
4. Ensure Entity ID and ACS URL match what you configured in Entra.
5. Save.

6.6 Assign Users and Groups to the App

1. In the Langdock SAML SSO enterprise app:
   • Go to Users and groups.
2. Click Add user/group.
3. Assign:
   • Individual users, and/or
   • Security groups (recommended).
4. Only assigned users can log in via SAML to Langdock.

6.7 Test SAML SSO in Entra

1. In the app, go to Single sign-on → Test.
2. Use:
   • Sign in as current user or
   • Copy the App sign-on URL and open it in a private browser.
3. Verify you can log into Langdock and that attributes are correctly passed.

---

7. SCIM Provisioning with Microsoft Entra ID

7.1 Enable SCIM in Langdock

1. In Langdock, go to Settings → SCIM / Provisioning.
2. Enable SCIM.
3. Copy:
   • SCIM Base URL (e.g., https://api.langdock.com/scim/v2)
   • **Bearer Token / API Token`.

7.2 Configure Provisioning in Entra

1. In Microsoft Entra admin center, open the Langdock enterprise app.
2. Under Manage, click Provisioning.
3. Set Provisioning Mode to Automatic.
4. In Admin Credentials:
   • Tenant URL: Langdock SCIM base URL.
   • Secret Token: Langdock SCIM token.
5. Click Test Connection; fix any errors if the test fails.
6. Save.

7.3 Configure Mappings

Under Provisioning → Mappings:

1. Click Provision Azure AD Users.

2. Ensure mappings such as:

   • userPrincipalName or mail → userName
   • givenName → name.givenName
   • surname → name.familyName
   • accountEnabled → active

3. If Langdock supports group-based roles, also configure Provision Azure AD Groups as needed.

4. Save mappings.

7.4 Scope Provisioning

In the Settings section of the Provisioning blade:

1. Set Scope:
   • Sync only assigned users and groups (recommended), or
   • Sync all users and groups (use with care).
2. If using assigned-only:
   • Go to Users and groups for the app.
   • Assign the users/groups you want provisioned in Langdock.

7.5 Start Provisioning

1. In Provisioning → Overview, click Start provisioning.
2. Initial sync can take a few minutes to several hours depending on directory size.
3. Check the Provisioning logs to confirm users are being created/updated in Langdock.

7.6 Test SCIM Provisioning in Entra

1. Add a test user to the app (via Users and groups).
2. Wait for provisioning or click Provision on demand if available.
3. Verify in Langdock that:
   • The user is created with correct attributes.
4. Remove or disable the user in Entra, then confirm they are deactivated in Langdock.

---

8. Recommended Attribute and Group Mappings

For consistent behavior across Okta and Microsoft Entra ID:

Core attributes

• userName → user’s email
• name.givenName → first name
• name.familyName → last name
• emails[type eq "work"].value → email (if supported)
• active → user status / accountEnabled

Group-based roles (if supported by Langdock)

• Map IdP groups to Langdock roles or teams, for example:
  • langdock-admins → Admin role
  • langdock-editors → Editor role
  • langdock-viewers → Viewer role

Check Langdock’s documentation for any specific attribute names or role mapping conventions.

---

9. Security and Governance Best Practices

• Test with a pilot group first
  • Start with a small group to validate login and provisioning.
• Enforce MFA in your IdP
  • Use Okta or Entra MFA/Conditional Access; Langdock will inherit this security via SAML.
• Limit SCIM tokens
  • Store SCIM tokens in a secure password vault.
  • Rotate tokens periodically and revoke old ones.
• Align deprovisioning
  • Confirm that disabling a user in the IdP quickly revokes access to Langdock.
• Monitor logs
  • Use IdP logs and Langdock audit logs to track sign-in and provisioning activity.

---

10. Troubleshooting Common Issues

Login loop / “Unauthorized” errors

• Check Entity ID and ACS URL are identical in Langdock and IdP.
• Ensure SAML certificate hasn’t expired.
• Confirm user is assigned to the app in Okta/Entra.

Missing attributes (wrong name, no email, etc.)

• Verify attribute/claim mapping in the IdP.
• Confirm the attribute exists for the user (e.g., mail populated in Entra).

SCIM provisioning failures

• Check token validity and SCIM base URL.
• Use Test connection within Okta/Entra.
• Review error messages in IdP provisioning logs.
• Ensure necessary attributes (like userName) are required and mapped.

Users not deprovisioned

• Verify Deactivate Users is enabled in provisioning settings.
• Confirm user is unassigned or disabled in your IdP.
• Check for provisioning scope restrictions (assigned-only vs. all users).

---

11. Summary

To set up Langdock with SAML SSO and SCIM provisioning in Okta or Microsoft Entra ID:

1. Configure SAML SSO

   • Create an app (Okta / Entra).
   • Set Langdock Entity ID and ACS URL.
   • Map required claims (email, first/last name, groups).
   • Import IdP metadata into Langdock and save.
   • Assign test users and verify login.

2. Configure SCIM Provisioning

   • Enable SCIM in Langdock and obtain base URL + token.
   • Set up provisioning (API integration/automatic provisioning) in Okta/Entra.
   • Map user attributes and choose scope.
   • Assign users/groups, start provisioning, and test lifecycle operations.

With SAML SSO and SCIM in place, Langdock becomes fully integrated with your identity platform, providing secure, centralized authentication and automated user lifecycle management.