Enterprise Security Controls

This page documents the enterprise security controls implemented in the current Workestra app. These controls are configured by workspace admin or owner users under Settings > Security.

Control matrix

Required role

Security administration APIs use the same workspace-admin guard:

1. The request must include a valid Bearer token.
2. The token must resolve to the current Supabase user.
3. The user must be a member of the target workspace with role admin or owner.

Non-admin users can read ordinary workspace settings where RLS allows it, but they cannot change SAML, SCIM, domain, IP allowlist, or workspace security policy settings.

SAML SSO

Setup

1. Open Settings > Security > SAML SSO.
2. Copy the Workestra service-provider values into your IdP:
   • SP Entity ID / metadata URL
   • Assertion Consumer Service URL
   • Workspace login URL
3. Export metadata XML from the IdP and paste it into Workestra.
4. Save the metadata. Workestra parses the IdP entity ID, SSO URL, and certificate.
5. Enable SSO after the certificate is present.

Runtime checks

The SAML ACS endpoint rejects responses that fail any of these checks:

• Missing SAMLResponse
• Unsigned response
• InResponseTo mismatch with the login request cookie
• Audience, destination, recipient, or issuer mismatch
• Failed XML signature verification in production
• Expired assertion

Successful SAML login finds or creates the user, adds a missing workspace membership as member, records a SAML session row, and redirects through a Supabase magic-link session exchange.

Current caveats

• Group-to-role mapping is not documented as an implemented admin control.
• Newly provisioned SAML users default to member.
• SAML config update/delete actions require recent step-up verification.

SCIM 2.0

Setup

1. Open Settings > Security > SCIM 2.0 Provisioning.
2. Copy the SCIM base URL:

https://workestra.app/api/scim/v2/{workspace_id}

3. Generate a named token for your IdP.
4. Copy the raw token immediately. It is shown once.
5. Configure the IdP to send Authorization: Bearer {token}.

Supported surfaces

Tokens are stored hashed, show only a prefix in the UI after creation, track last_used_at, and can be revoked. SCIM traffic is rate-limited per token after successful authentication.

Domain control

Domain control verifies that the workspace controls an email domain.

1. Open Settings > Security > Domain control.
2. Enter the domain, for example example.com.
3. Add the DNS TXT value shown by Workestra:

workestra-domain-verify={verification_token}

4. Click Verify after DNS propagation.

Workestra normalizes domain input, blocks Workestra-owned default hosts, and refuses a domain that is already verified for another workspace. Verification succeeds only when DNS TXT lookup returns the expected token.

IP allowlist

The IP allowlist accepts IPv4 and IPv6 CIDR entries. Admins can label entries for operational clarity.

When enforcement is off, the allowlist is stored but not enforced. When enforcement is on:

• Matching CIDR: request may continue.
• No CIDRs configured: request is blocked.
• No matching CIDR: request is blocked.
• Policy-check failure: request is blocked.

Because an empty enforced list fails closed, add at least one trusted CIDR before enabling enforcement.

Login OTP

The Require login OTP switch is configured on the same page as the IP allowlist. When enabled for any workspace the user belongs to, password sign-in requires a six-digit email code.

Security details:

• Codes are stored as SHA-256 hashes.
• Codes expire after 10 minutes.
• Each new code consumes previous outstanding codes for that user.
• Five failed attempts block that code.
• OTP request and verification routes use durable rate limits.
• OTP send, success, and failed verification events are audit logged.

Sessions and recovery expectations

Workestra records per-session OTP and step-up verification in auth_session_verifications. Protected admin mutations can require recent verification, and successful login OTP marks the active session as verified.

Current limitations to communicate during enterprise rollout:

• There is no documented self-service active-session list for end users in the public app docs.
• SAML single logout is not documented as implemented.
• Admin-side bulk user deletion and account deletion revoke sessions, but workspace admins do not have a general active-session console in the public docs.

Audit evidence

Security control changes write audit events, including:

• saml.config_updated
• saml.config_deleted
• saml.login_success
• scim.token_created
• scim.token_revoked
• domain.claim_started
• domain.verified
• domain.claim_deleted
• ip_allowlist.added
• ip_allowlist.removed
• ip_allowlist.policy_updated
• auth.login_otp_sent
• auth.login_otp_verified
• auth.login_otp_failed.*

Review Audit Log for the general audit-log workflow.