TorkTORK
Docs/Enterprise/SSO

Enterprise SSO

Single Sign-On with SAML 2.0, Okta, and Azure AD

SAML 2.0OktaAzure ADEnterprise

Overview

Tork Enterprise SSO allows your organization to use your existing identity provider for authentication. Users can log in with their corporate credentials, providing a seamless and secure experience while maintaining centralized access control.

SAML 2.0

Industry-standard protocol supported by most identity providers

  • Universal IdP support
  • SP-initiated SSO
  • Single Logout (SLO)
  • Attribute mapping

Okta

Native integration with Okta's identity platform

  • OAuth 2.0 + OIDC
  • Group sync
  • API token support
  • SCIM provisioning ready

Azure AD

Microsoft identity platform integration for Microsoft 365

  • Microsoft Graph API
  • Group membership sync
  • Conditional access
  • Multi-tenant support

Key Features

Just-in-Time Provisioning

Automatically create user accounts when they first log in via SSO

Role Mapping

Map IdP groups to Tork roles for automatic permission assignment

SSO Enforcement

Require all organization users to authenticate via SSO

Domain Restriction

Restrict SSO access to specific email domains

SAML 2.0 Setup

Step 1: Get Tork SP Metadata

Download the Service Provider metadata to configure your Identity Provider.

# Get SP metadata for your SSO configuration
curl https://api.tork.network/v1/sso/{config_id}/metadata \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o tork-sp-metadata.xml

Step 2: Configure Your IdP

Use the following values to configure your SAML Identity Provider:

Entity ID:https://tork.network
ACS URL:https://tork.network/api/v1/sso/saml/acs
SLO URL:https://tork.network/api/v1/sso/saml/slo
NameID Format:emailAddress

Step 3: Create SSO Configuration

curl -X POST https://api.tork.network/v1/sso \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "saml",
    "name": "Corporate SSO",
    "saml_entity_id": "https://idp.company.com/saml",
    "saml_sso_url": "https://idp.company.com/sso",
    "saml_slo_url": "https://idp.company.com/slo",
    "saml_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    "is_active": true,
    "allowed_domains": ["company.com"],
    "attribute_mapping": {
      "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
      "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
      "groups": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
    }
  }'

Okta Setup

Step 1: Create Okta Application

  1. Go to Okta Admin Console
  2. Navigate to Applications → Create App Integration
  3. Select "OIDC - OpenID Connect"
  4. Choose "Web Application"
  5. Set Sign-in redirect URI to: https://tork.network/api/v1/sso/okta/callback
  6. Copy the Client ID and Client Secret

Step 2: Create SSO Configuration

curl -X POST https://api.tork.network/v1/sso \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "okta",
    "name": "Okta SSO",
    "okta_domain": "company.okta.com",
    "okta_client_id": "0oa1234567890abcdef",
    "okta_client_secret": "your-client-secret",
    "is_active": true,
    "allowed_domains": ["company.com"],
    "role_mapping": {
      "Tork Admins": "admin",
      "Tork Users": "member"
    }
  }'

Azure AD Setup

Step 1: Register Azure AD Application

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory → App registrations
  3. Click "New registration"
  4. Set Redirect URI to: https://tork.network/api/v1/sso/azure/callback
  5. Under Certificates & secrets, create a new client secret
  6. Under API permissions, add: openid, profile, email, User.Read
  7. Copy the Application (client) ID and Directory (tenant) ID

Step 2: Create SSO Configuration

curl -X POST https://api.tork.network/v1/sso \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "azure_ad",
    "name": "Azure AD SSO",
    "azure_tenant_id": "your-tenant-id",
    "azure_client_id": "your-client-id",
    "azure_client_secret": "your-client-secret",
    "is_active": true,
    "allowed_domains": ["company.onmicrosoft.com", "company.com"],
    "role_mapping": {
      "Tork Administrators": "admin",
      "Tork Users": "member"
    }
  }'

API Reference

GET/v1/sso

List all SSO configurations

POST/v1/sso

Create a new SSO configuration

GET/v1/sso/:id

Get SSO configuration details

PATCH/v1/sso/:id

Update SSO configuration

DELETE/v1/sso/:id

Delete SSO configuration

GET/v1/sso/:id/metadata

Download SP metadata XML

POST/v1/sso/:id/test

Test SSO configuration connectivity

Attribute Mapping

Map attributes from your Identity Provider to Tork user properties.

Tork AttributeDescriptionRequired
emailUser's email address
firstNameUser's first nameOptional
lastNameUser's last nameOptional
groupsUser's group memberships (for role mapping)Optional

Role Mapping

Automatically assign Tork roles based on IdP group membership.

{
  "role_mapping": {
    "IT Administrators": "owner",
    "Security Team": "admin",
    "Developers": "member",
    "Contractors": "viewer"
  }
}

Note

The first matching group determines the role. Order your role mapping from highest to lowest privilege.

Troubleshooting

SAML Response Invalid

  • Verify the IdP certificate is correct and not expired
  • Check that the ACS URL matches exactly in your IdP configuration
  • Ensure the NameID format matches your configuration
  • Verify clock synchronization between Tork and your IdP

User Not Provisioned

  • Check if JIT provisioning is enabled
  • Verify the user's email domain is in allowed_domains
  • Ensure the email attribute is being sent by the IdP

OAuth Token Exchange Failed

  • Verify the client ID and secret are correct
  • Check that the redirect URI matches exactly
  • Ensure the application has the required API permissions

Related Documentation

API Authentication

API keys and token management

Security

Security best practices