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>
8.0 KiB
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
- Enterprise Plan - SSO requires an Enterprise subscription
- Admin Access - You must be an organization owner
- IdP Access - Admin access to your identity provider
- 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
- Log in to Okta Admin Console
- Go to Applications → Applications
- Click Create App Integration
- Select SAML 2.0 → Next
- Configure:
- App name: Gitgram TimeMachine
- App logo: (optional)
- 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 |
Step 3: Attribute Statements
Add these attribute mappings:
| Name | Value |
|---|---|
| user.email | |
| firstName | user.firstName |
| lastName | user.lastName |
Step 4: Complete Setup
- Click Next → Finish
- Go to Sign On tab
- Click View SAML setup instructions
- 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
- Go to Azure Portal
- Navigate to Azure Active Directory → Enterprise applications
- Click New application → Create your own application
- Name:
Gitgram TimeMachine - Select Integrate any other application (Non-gallery)
- Click Create
Step 2: Configure Single Sign-On
- Go to Single sign-on → SAML
- 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.mailgivenname→ user.givennamesurname→ user.surname
Step 4: Get Federation Metadata
- In SAML Signing Certificate section
- 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
- Go to Google Admin Console
- Navigate to Apps → Web and mobile apps
- Click Add app → Add custom SAML app
- Name:
Gitgram TimeMachine - Click Continue
Step 2: Download IdP Metadata
- Download the IdP metadata XML file
- 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 | |
| Name ID | Basic Information > Primary email |
Step 4: Attribute Mapping
| Google Directory | App Attribute |
|---|---|
| Primary email | |
| First name | firstName |
| Last name | lastName |
Step 5: Enable for Users
- Click User access
- 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 |
|---|---|---|
| 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/falsedefaultRole: "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
- Enable SSO enforcement for all enterprise orgs
- Restrict domains to your company's email domains
- Regular audits of SSO access logs
- Certificate rotation - Update SAML certificates before expiry
- Test thoroughly before enabling enforcement
Support
For enterprise SSO support:
- Email: enterprise@gitgram.app
- Documentation: https://timemachine.gitgram.app/docs/enterprise
- API Reference: https://timemachine.gitgram.app/docs/api/sso