SSO & SCIM

Use this guide to configure enterprise identity onboarding end-to-end.

Overview

Single Sign-On (SSO) and SCIM provisioning eliminate manual user management for Octomil workspaces. With SSO, your team authenticates through your existing identity provider (Okta, Azure AD, Google Workspace, etc.) instead of managing separate credentials. SCIM automates user lifecycle management -- when someone joins or leaves your organization in the IdP, their Octomil access is created or revoked automatically.

This matters for federated learning deployments because:

• Compliance: HIPAA, SOC 2, and GDPR audits require centralized identity governance. SSO provides a single authentication boundary; SCIM provides an auditable provisioning trail.
• Operational overhead: Without SCIM, admins must manually create and deprovision Octomil accounts. At scale (50+ users), this becomes a significant burden and a security risk when offboarding is delayed.
• Least privilege: Role mapping ensures that data scientists, ML engineers, and platform admins receive appropriate permissions without manual role assignment.

SAML vs OIDC: Choosing a Protocol

Octomil supports both SAML 2.0 and OpenID Connect (OIDC) for SSO. Choose based on your identity provider and requirements.

Feature	SAML 2.0	OIDC
Protocol maturity	Established, widely supported	Modern, simpler to implement
Token format	XML assertions	JWT tokens
Best for	Enterprise IdPs (Okta, ADFS, PingFederate)	Cloud-native IdPs (Auth0, Google, Azure AD B2C)
Session management	Relies on IdP session cookies	Token-based with refresh
Attribute mapping	Via SAML attribute statements	Via OIDC claims
Octomil recommendation	Use when your IdP prefers SAML	Use when you want simpler setup or already use OIDC

If your IdP supports both, OIDC is generally simpler to configure and debug. SAML is the safer choice if your security team has existing SAML policies or if your IdP's OIDC support is limited.

Prerequisites

• Octomil app deployed (https://app.octomil.com)
• SSO and SCIM are enabled for your workspace by an Octomil admin
• Octomil identity service configured for your workspace
• Access to your identity provider's admin console (Okta, Azure AD, Google Workspace, etc.)
• The ACS URL and SP Entity ID from your Octomil workspace settings (found under Dashboard -> Settings -> Identity)

1. Configure identity in Onboarding

Navigate to Dashboard -> Onboarding -> Identity and provisioning.

• Select Identity mode = Enterprise SSO
• Enter the organization and SSO connection identifiers from your Octomil workspace
• If using SCIM, enable SCIM sync and enter the SCIM connection identifier
• Save

After saving, Octomil validates connectivity and displays the connection status. If the status shows an error, verify your identity service credentials are correct and that the organization ID matches.

2. Configure the identity webhook

Create one webhook to:

• URL: https://app.octomil.com/api/v1/scim/webhook
• Signing secret: configure this in your identity provider and Octomil environment
• Headers required by Octomil: signature and timestamp headers for webhook verification

Subscribe to member lifecycle events (create, update, delete) and SSO connection events.

Store the webhook signing secret securely in your deployment's secret manager. Never commit this value to source control.

3. Role Mapping Configuration

Octomil maps IdP group memberships or SAML/OIDC attributes to internal roles. Configure role mapping under Dashboard -> Onboarding -> Role mapping.

Default role mappings

IdP Group / Attribute	Octomil Role	Capabilities
octomil-owners	owner	Full workspace control, billing, delete workspace
octomil-admins	admin	Manage users, devices, models, experiments
octomil-members	member	View dashboard, submit training updates, view models

Custom mapping rules

You can define custom mappings based on SAML attribute statements or OIDC claims:

# Example role mapping configuration
role_mappings:
  - source_attribute: "groups"
    match_value: "ml-platform-team"
    octomil_role: "admin"
  - source_attribute: "department"
    match_value: "data-science"
    octomil_role: "member"
  - source_attribute: "groups"
    match_value: "engineering-leads"
    octomil_role: "admin"

Role mapping is evaluated in order. The first matching rule wins. If no rule matches, the user is assigned the member role by default.

SAML attribute configuration

In your IdP, ensure the SAML assertion includes a group membership attribute. For Okta:

1. Go to Applications -> Octomil -> SAML Settings -> Attribute Statements
2. Add a group attribute: Name = groups, Filter = Matches regex with octomil-.*
3. Save and re-test the SSO flow

4. SCIM Attribute Mapping

SCIM synchronizes user attributes from your IdP to Octomil. The following attributes are mapped:

SCIM Attribute	Octomil Field	Required
userName	email	Yes
name.givenName	first_name	Yes
name.familyName	last_name	Yes
active	is_active	Yes
displayName	display_name	No
title	job_title	No
groups	Role mapping input	No

When a SCIM member.delete event fires (e.g., user deprovisioned in Okta), Octomil:

1. Sets is_active = false on the user record
2. Revokes all active sessions for the user
3. Revokes all device tokens issued by the user
4. Logs the deprovisioning event to the audit trail

This ensures that deprovisioned users cannot access the platform or any devices they previously managed.

5. Validate diagnostics

In Onboarding -> Identity diagnostics verify:

• Identity service configured
• SSO/SCIM connection status is healthy
• Last SCIM webhook timestamp updates after test delivery
• Last SSO success updates after test login

Use Validate role mapping to test role hints before enabling broad sync.

Diagnostic checklist

1. SSO login test: Have a test user authenticate through your IdP. Verify they land on the Octomil dashboard with the correct role.
2. SCIM push test: Create a test user in your IdP. Within 60 seconds, verify the user appears in Dashboard -> Members.
3. SCIM deprovision test: Deactivate the test user in your IdP. Verify their Octomil account is deactivated and sessions are revoked.
4. Role mapping test: Assign the test user to different IdP groups and verify the Octomil role updates on next login.

6. Enforce admin controls

For strict environments:

• Keep Require explicit admin provisioning for elevated roles enabled
• This prevents admin role hints from auto-promoting unless approved

Additional hardening options:

• Restrict SSO-only login: Disable password-based login entirely under Dashboard -> Settings -> Authentication. This forces all users through your IdP.
• Session timeout: Set the maximum session duration under Dashboard -> Settings -> Security. Recommended: 8 hours for members, 4 hours for admins.
• IP allowlisting: If your IdP supports it, restrict SAML/OIDC callbacks to known IP ranges.

Monitoring SSO Health

Monitor the health of your SSO and SCIM integrations using the built-in diagnostics and your own observability stack.

Key metrics to watch

• SSO login success rate: Should be above 99.5%. A drop indicates IdP misconfiguration or certificate expiry.
• SCIM webhook delivery rate: Should be 100%. Failed deliveries mean users are not being provisioned or deprovisioned.
• SCIM sync latency: Time between IdP event and Octomil processing. Should be under 30 seconds.
• Role mapping mismatches: Count of users whose IdP group does not match an Octomil role mapping rule.

Prometheus metrics

If you have the monitoring stack configured, the following metrics are exported:

Key exported metrics include SSO login success/failure counts by provider, SCIM webhook processing counts by event type and status, and SCIM sync latency.

Set up alerts for SSO login failures exceeding 5 per hour.

Security Best Practices

• Rotate the SCIM webhook signing secret quarterly. Update the secret in both your IdP and Octomil environment variables simultaneously to avoid downtime.
• Use a dedicated service account in your IdP for the SCIM connection. Do not use a personal admin account.
• Enable MFA for all Octomil admins regardless of SSO enforcement. SSO delegates authentication but MFA adds a second factor at the IdP level.
• Audit role escalations monthly. Review the audit log for any role_changed events where the new role is admin or owner.
• Test deprovisioning regularly. Run a quarterly drill to verify that deprovisioned IdP users lose Octomil access within your SLA (recommended: under 5 minutes).

Troubleshooting

• SSO/SCIM disabled: verify identity integrations are enabled for your workspace
• Invalid webhook signature: rotate and re-save the webhook signing secret
• organization_not_mapped: verify stytch_organization_id matches onboarding
• SAML assertion invalid: check that the ACS URL in your IdP matches the one shown in Octomil workspace settings. Certificate mismatches are the most common cause -- re-download the SP certificate from Dashboard -> Settings -> Identity.
• SCIM user not created: verify the SCIM endpoint URL is correct and that the SCIM bearer token has not expired. Check the webhook delivery logs in your IdP.
• Role not assigned: confirm that the IdP group name exactly matches the role mapping rule (case-sensitive). Use the Validate role mapping tool in diagnostics to test.
• User deprovisioned but still has access: Check that the SCIM member.delete webhook is subscribed and that recent webhook deliveries show a 200 response. If the webhook was delivered but the user is still active, contact Octomil support.

Related Docs

• Security Architecture -- full security model overview
• Device Token Lifecycle -- how device tokens interact with user sessions
• Migration from Org API Keys -- moving from embedded API keys to token-based auth
• Workspace Settings -- workspace-level configuration
• Logs and Audit -- audit trail for identity events