SSO Integration

Turqoa supports Single Sign-On (SSO) through SAML 2.0 and OpenID Connect (OIDC), allowing operators and administrators to authenticate using your organization's existing identity provider.

Overview

SSO eliminates the need for separate Turqoa credentials. Users authenticate through your corporate identity provider (IdP), and Turqoa maps their identity attributes to internal roles and permissions. This provides:

• Centralized access control --- Manage Turqoa access from your existing IdP
• Reduced credential sprawl --- No additional passwords for operators to manage
• Compliance --- Authentication events are logged in both Turqoa and your IdP
• MFA enforcement --- Leverage your IdP's multi-factor authentication policies

SAML 2.0 Configuration

Turqoa Service Provider Metadata

Turqoa exposes its SAML metadata at:

https://<turqoa-domain>/auth/saml/metadata

Provide this URL to your IdP administrator to establish the trust relationship.

IdP Configuration in Turqoa

# turqoa-config.yaml
auth:
  sso:
    provider: saml
    saml:
      idp_metadata_url: https://login.example.com/federationmetadata/saml
      idp_entity_id: https://sts.example.com/adfs/services/trust
      certificate_file: /etc/turqoa/certs/idp-signing.pem
      sign_requests: true
      signed_assertions: true
      want_encrypted_assertions: false
      allowed_clock_skew_seconds: 120

Azure AD / Entra ID Setup

1. In the Azure portal, navigate to Enterprise Applications > New Application > Non-gallery application.
2. Name the application "Turqoa" and configure SAML SSO.
3. Set the Identifier (Entity ID) and Reply URL from the table above.
4. Configure the following claims:

email       → user.mail
first_name  → user.givenname
last_name   → user.surname
groups      → user.groups
department  → user.department

OIDC Configuration

For identity providers that support OpenID Connect (Okta, Auth0, Azure AD):

auth:
  sso:
    provider: oidc
    oidc:
      issuer: https://login.example.com
      client_id: ${OIDC_CLIENT_ID}
      client_secret: ${OIDC_CLIENT_SECRET}
      redirect_uri: https://<turqoa-domain>/auth/oidc/callback
      scopes:
        - openid
        - profile
        - email
        - groups
      response_type: code
      token_endpoint_auth_method: client_secret_post

Discovery

Turqoa automatically retrieves OIDC configuration from the well-known endpoint:

https://<issuer>/.well-known/openid-configuration

No manual endpoint configuration is required when the issuer URL is set correctly.

User Provisioning

Turqoa supports two provisioning models:

JIT Provisioning

When a user authenticates via SSO for the first time, Turqoa creates a local user record using claims from the SAML assertion or OIDC token. The user is assigned a default role (configurable).

auth:
  provisioning:
    mode: jit
    default_role: operator
    auto_activate: true
    update_on_login: true   # Sync name/email/groups on each login

Role Mapping

Map IdP groups or attributes to Turqoa roles to automate permission assignment:

auth:
  role_mapping:
    rules:
      - match:
          attribute: groups
          contains: "Port-Admins"
        assign_role: admin
      - match:
          attribute: groups
          contains: "Gate-Operators"
        assign_role: operator
      - match:
          attribute: groups
          contains: "Security-Team"
        assign_role: security_operator
      - match:
          attribute: department
          equals: "IT"
        assign_role: admin
    default_role: viewer

Available Roles

Code Examples

Verifying SSO Configuration

# Test SAML metadata retrieval
curl -s https://turqoa.example.com/auth/saml/metadata | xmllint --format -

# Test OIDC discovery
curl -s https://login.example.com/.well-known/openid-configuration | jq .

Programmatic Role Check

from turqoa.auth import get_current_user

user = get_current_user(request)
if user.has_role("admin"):
    # Allow system configuration
    pass
elif user.has_role("operator"):
    # Allow gate operations
    pass

Note: SSO sessions in Turqoa respect your IdP's session lifetime. When a user's IdP session expires, they are redirected to re-authenticate on their next Turqoa request.