This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/aitimemachine/docs/SSO_SAML_SETUP.md
caelum0x 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as
opaque submodule gitlinks on GitHub) into fully-tracked first-party content.

AITM now merges its 7 vendored repos as first-party engines:
- memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts
- git: vendored C git (bundled binary) + gitnexus (in-process code intelligence)
- agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess)

Includes the full session's product build: Gitgram web/mobile/backend features,
AITM website/CLI/MCP, the unified memory layer, engine build tooling
(scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md),
and extensive test suites.

Build artifacts, node_modules, external/, and gemini-cli are gitignored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-23 14:14:09 +03:00

8.0 KiB

SSO/SAML Enterprise Setup Guide

This guide explains how to configure SAML SSO for enterprise organizations using Gitgram TimeMachine.

Overview

SSO/SAML is available for Enterprise plan organizations. It enables:

  • Single Sign-On with your identity provider (IdP)
  • Centralized user management
  • Just-in-time user provisioning
  • Enforced authentication policies
  • Domain-restricted access

Supported Identity Providers

Gitgram TimeMachine supports SAML 2.0 SSO with any compatible IdP:

Provider Status Setup Guide
Okta Fully Supported Okta Setup
Azure AD Fully Supported Azure AD Setup
Google Workspace Fully Supported Google Setup
OneLogin Fully Supported OneLogin Setup
Auth0 Fully Supported Auth0 Setup
Other SAML 2.0 Supported Generic SAML Setup

Prerequisites

  1. Enterprise Plan - SSO requires an Enterprise subscription
  2. Admin Access - You must be an organization owner
  3. IdP Access - Admin access to your identity provider
  4. Verified Domain - Your email domain must be verified

API Endpoints

Get SSO Configuration

GET /v1/sso/config/{org_id}
Authorization: Bearer {api_key}

Update SSO Configuration

PUT /v1/sso/config/{org_id}
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "enabled": true,
  "provider": "saml",
  "enforceSSO": false,
  "allowedDomains": ["yourcompany.com"],
  "jitProvisioning": true,
  "defaultRole": "member"
}

Verify Domain

POST /v1/sso/verify-domain/{org_id}
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "domain": "yourcompany.com"
}

List Supported Providers

GET /v1/sso/providers

Okta Setup

Step 1: Create SAML App in Okta

  1. Log in to Okta Admin Console
  2. Go to Applications → Applications
  3. Click Create App Integration
  4. Select SAML 2.0 → Next
  5. Configure:
    • App name: Gitgram TimeMachine
    • App logo: (optional)
  6. Click Next

Step 2: Configure SAML Settings

Enter the following values:

Setting Value
Single sign-on URL https://clerk.gitgram.app/v1/saml
Audience URI (SP Entity ID) https://clerk.gitgram.app
Name ID format EmailAddress
Application username Email

Step 3: Attribute Statements

Add these attribute mappings:

Name Value
email user.email
firstName user.firstName
lastName user.lastName

Step 4: Complete Setup

  1. Click Next → Finish
  2. Go to Sign On tab
  3. Click View SAML setup instructions
  4. Copy the Identity Provider metadata URL

Step 5: Configure in Gitgram TimeMachine

PUT /v1/sso/config/{org_id}
{
  "enabled": true,
  "provider": "saml",
  "saml": {
    "metadataUrl": "https://your-org.okta.com/app/xxx/sso/saml/metadata"
  },
  "allowedDomains": ["yourcompany.com"]
}

Azure AD Setup

Step 1: Create Enterprise Application

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory → Enterprise applications
  3. Click New application → Create your own application
  4. Name: Gitgram TimeMachine
  5. Select Integrate any other application (Non-gallery)
  6. Click Create

Step 2: Configure Single Sign-On

  1. Go to Single sign-on → SAML
  2. Edit Basic SAML Configuration:
Setting Value
Identifier (Entity ID) https://clerk.gitgram.app
Reply URL (ACS URL) https://clerk.gitgram.app/v1/saml
Sign on URL https://timemachine.gitgram.app/sso/{org_slug}

Step 3: Attributes & Claims

Configure claims mapping:

  • emailaddress → user.mail
  • givenname → user.givenname
  • surname → user.surname

Step 4: Get Federation Metadata

  1. In SAML Signing Certificate section
  2. Copy App Federation Metadata Url

Step 5: Configure in Gitgram TimeMachine

PUT /v1/sso/config/{org_id}
{
  "enabled": true,
  "provider": "saml",
  "saml": {
    "metadataUrl": "https://login.microsoftonline.com/{tenant}/federationmetadata/2007-06/federationmetadata.xml"
  }
}

Google Workspace Setup

Step 1: Create SAML App

  1. Go to Google Admin Console
  2. Navigate to Apps → Web and mobile apps
  3. Click Add app → Add custom SAML app
  4. Name: Gitgram TimeMachine
  5. Click Continue

Step 2: Download IdP Metadata

  1. Download the IdP metadata XML file
  2. Or copy the SSO URL, Entity ID, and Certificate

Step 3: Configure Service Provider

Enter these values:

Setting Value
ACS URL https://clerk.gitgram.app/v1/saml
Entity ID https://clerk.gitgram.app
Name ID format EMAIL
Name ID Basic Information > Primary email

Step 4: Attribute Mapping

Google Directory App Attribute
Primary email email
First name firstName
Last name lastName

Step 5: Enable for Users

  1. Click User access
  2. Enable for your organization or specific OUs

Generic SAML Setup

For other SAML 2.0 providers:

Required Information from IdP

You'll need:

  • IdP Metadata URL or XML
  • IdP SSO URL
  • IdP Entity ID
  • X.509 Certificate

Service Provider Details

Provide to your IdP:

Setting Value
SP Entity ID https://clerk.gitgram.app
ACS URL https://clerk.gitgram.app/v1/saml
SLO URL https://clerk.gitgram.app/v1/saml/logout
Name ID Format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Required Attributes

Attribute Required Description
email Yes User's email address
firstName No User's first name
lastName No User's last name

Enforcing SSO

Once SSO is working, you can enforce it for all organization members:

PUT /v1/sso/config/{org_id}
{
  "enforceSSO": true
}

When enforced:

  • Users must authenticate via SSO
  • Password login is disabled
  • API keys still work normally

Just-in-Time Provisioning

JIT provisioning automatically creates user accounts on first SSO login:

PUT /v1/sso/config/{org_id}
{
  "jitProvisioning": true,
  "defaultRole": "member"
}

Options:

  • jitProvisioning: true/false
  • defaultRole: "member" or "admin"

Domain Verification

Before enabling SSO, verify your domain:

Step 1: Request Verification Token

POST /v1/sso/verify-domain/{org_id}
{ "domain": "yourcompany.com" }

Response:

{
  "domain": "yourcompany.com",
  "verification_method": "dns",
  "verification_token": "aitm-verify-xxx",
  "instructions": [
    "Add TXT record: _gitgram-timemachine.yourcompany.com",
    "Value: aitm-verify-xxx"
  ]
}

Step 2: Add DNS Record

Add a TXT record:

  • Name: _gitgram-timemachine
  • Value: The verification token

Step 3: Verify

POST /v1/sso/verify-domain/{org_id}/check
{ "domain": "yourcompany.com" }

Troubleshooting

"SAML Response Invalid"

  • Check clock synchronization between IdP and SP
  • Verify ACS URL is correct
  • Ensure certificate hasn't expired

"User Not Found"

  • Enable JIT provisioning
  • Verify email attribute is mapped correctly
  • Check domain restrictions

"Access Denied"

  • Verify user is assigned to the SAML app in IdP
  • Check organization membership
  • Ensure SSO is enabled for the org

Security Recommendations

  1. Enable SSO enforcement for all enterprise orgs
  2. Restrict domains to your company's email domains
  3. Regular audits of SSO access logs
  4. Certificate rotation - Update SAML certificates before expiry
  5. Test thoroughly before enabling enforcement

Support

For enterprise SSO support: