| # SAML Single Sign-On |
|
|
| This application now acts as a multi-tenant SAML 2.0 Service Provider (SP) using [`python3-saml`](https://github.com/onelogin/python3-saml). Each customer/tenant can upload their Identity Provider (IdP) metadata and control how SAML attributes map to local users. SAML logins reuse the same session/JWT creation flow as password-based logins. |
|
|
| ## Components |
|
|
| - **Tenants (`/api/saml/tenants`)** – logical customers. Tenants can allow/disallow password auth and host one or more SAML configs. |
| - **SAML configurations (`/api/saml/configs`)** – derived from IdP metadata. Store IdP entity ID, SSO/SLO endpoints, certificates, attribute mappings, and SP overrides (ACS URL, entity ID, etc.). |
| - **External identities** – map SAML `NameID`/email values to local users and keep a copy of the attributes returned by the IdP. |
|
|
| > **Migrations:** After pulling this change, run `flask db migrate && flask db upgrade` (or the equivalent for your environment) to create the new tables/columns. |
|
|
| ## Required Environment Variables |
|
|
| | Variable | Purpose | |
| | --- | --- | |
| | `PUBLIC_BASE_URL` | Public HTTPS base URL that IdPs can reach (e.g., `https://attstore.example.com`). Used to calculate ACS/SLO endpoints inside the generated metadata. | |
| | `SAML_SP_CERTIFICATE` | Optional PEM certificate if you need to sign Authn/SLO requests. Leave unset for unsigned requests. | |
| | `SAML_SP_PRIVATE_KEY` | Private key that matches `SAML_SP_CERTIFICATE`. | |
|
|
| The legacy `FILE_STORAGE_BASE_URL` is still used for file downloads; it is **not** used for SAML. |
|
|
| ## Authenticating Admin API Calls |
|
|
| The `/api/saml/*` endpoints require a JWT (same as the rest of the admin API surface). Use an API token from **Settings → API Tokens** to mint a short-lived JWT and export both values for reuse: |
|
|
| ```bash |
| # Base URL (should match PUBLIC_BASE_URL) |
| export BASE_URL="https://attstore.example.com" |
| |
| # 1. Paste the API token generated in the UI |
| export TOKEN="dXNlcm5hbWU6c2VjcmV0Cg==" |
| |
| # 2. Exchange it for a JWT (requires jq) |
| export JWT_TOKEN=$(curl -s -X POST "$BASE_URL/v1/login" \ |
| -H 'Content-Type: application/json' \ |
| -d "{\"api_token\":\"$TOKEN\"}" | jq -r '.access_token') |
| |
| # 3. Use the JWT for all privileged calls |
| curl -H "Authorization: Bearer $JWT_TOKEN" "$BASE_URL/api/saml/tenants" |
| ``` |
|
|
| This keeps API tokens long-lived while every admin request runs with the scoped JWT. |
|
|
| ## Provisioning a Tenant & IdP Metadata |
|
|
| 1. **Create a tenant** |
| ```bash |
| curl -X POST "$BASE_URL/api/saml/tenants" \ |
| -H "Authorization: Bearer $JWT_TOKEN" \ |
| -H "Content-Type: application/json" \ |
| -d '{"name": "Acme Corp", "slug": "acme", "allow_password_auth": false}' |
| ``` |
|
|
| 2. **Create a SAML config** |
| ```bash |
| # Convert your IdP metadata into JSON-safe form (example path: tmp/GoogleIDPMetadata.xml) |
| export METADATA=$(jq -Rs . tmp/GoogleIDPMetadata.xml) |
| |
| curl -X POST "$BASE_URL/api/saml/configs" \ |
| -H "Authorization: Bearer $JWT_TOKEN" \ |
| -H "Content-Type: application/json" \ |
| -d "{ |
| \"tenant_id\": 1, |
| \"name\": \"Acme SSO\", |
| \"slug\": \"acme-sso\", |
| \"metadata_xml\": $METADATA, |
| \"attribute_mapping\": { |
| \"email\": \"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress\", |
| \"username\": \"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name\" |
| }, |
| \"auto_provision_users\": true |
| }" |
| ``` |
|
|
| The server parses the metadata, stores the IdP certificate and endpoints, and responds with derived SP URLs: |
|
|
| ```json |
| { |
| "id": 4, |
| "slug": "acme-sso", |
| "service_urls": { |
| "acs": "https://attstore.example.com/saml/acme-sso/acs", |
| "entity_id": "https://attstore.example.com/saml/acme-sso/metadata", |
| "slo": "https://attstore.example.com/saml/acme-sso/slo" |
| } |
| } |
| ``` |
|
|
| 3. **Hand the SP metadata to the IdP**\ |
| Each SAML config exposes SP metadata at `/saml/<slug>/metadata`. Provide this URL to the IdP (or download the XML and upload it manually). |
|
|
| ## Google Workspace Example |
|
|
| 1. **Create the custom SAML app** |
| - Google Admin Console → *Apps → Web and mobile apps → Add custom SAML app*. |
| - Download the IdP metadata XML provided during the wizard. |
|
|
| 2. **Configure URLs** |
| - **ACS URL**: `https://<your-domain>/saml/<slug>/acs` |
| - **Entity ID**: `https://<your-domain>/saml/<slug>/metadata` |
| - **Name ID**: `Email` (default) or whichever attribute you plan to map. |
|
|
| 3. **Upload metadata to Attestation Store** |
| - Call `POST /api/saml/configs` (above) using the downloaded metadata. |
| - Set `attribute_mapping.email` to `email` or `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. |
|
|
| 4. **Assign users**\ |
| In Google Admin, assign the SAML app to the users/groups who should access Attestation Store. |
|
|
| 5. **Test** |
| - Initiate login from Attestation Store: `/login` now shows "Continue with <Tenant>" buttons. |
| - Or IdP-initiated flows (if `allow_idp_initiated` is `true`). |
| - Watch the server logs for `saml_login_success` events; run through both ACS and SLO endpoints to confirm. |
|
|
| > **Local development tip:** When testing with Google, expose your dev server via `ngrok` or run it in a public environment so Google can reach `https://.../saml/<slug>/acs`. |
|
|
| ## Attribute Mapping & Auto-Provisioning |
|
|
| - `attribute_mapping`: JSON object mapping logical fields (`email`, `username`, `first_name`, `last_name`) to the IdP attribute names. Defaults to `email`, `username`, `firstName`, `lastName`. |
| - `auto_provision_users`: When `true`, the server creates a local user the first time it sees a new SAML identity. The user is placed in the tenant and assigned a random password (unused). |
| - When `auto_provision_users` is `false`, the assertion must match an existing user (by `NameID` or mapped email); otherwise the login fails. |
|
|
| All SAML identities are stored in the `external_identities` table with the assertion attributes for auditability. |
|
|
| ## Testing & Troubleshooting |
|
|
| 1. **Health check** – `/healthz` ensures DB access before testing. |
| 2. **Metadata validation** – hitting `/saml/<slug>/metadata` should return valid XML. Errors will appear in `system_logs` with `saml_metadata_error`. |
| 3. **ACS testing** – use the IdP test button or tools like [samltool.com](https://www.samltool.com/) to post assertions to `/saml/<slug>/acs`. |
| 4. **SLO** – ensure `/saml/<slug>/slo` works in both SP-initiated and IdP-initiated directions. |
| 5. **Logs** – search `system_logs` for `saml_*` events to trace configuration or login issues. |
|
|
| ## Tenant Management |
|
|
| ### API Endpoints |
|
|
| The following tenant management endpoints are available: |
|
|
| | Method | Endpoint | Description | |
| | --- | --- | --- | |
| | GET | `/api/saml/tenants` | List all tenants | |
| | POST | `/api/saml/tenants` | Create a new tenant | |
| | PATCH | `/api/saml/tenants/<id>` | Update a tenant | |
| | DELETE | `/api/saml/tenants/<id>` | Delete a tenant | |
|
|
| ### Deleting a Tenant |
|
|
| When you delete a tenant via `DELETE /api/saml/tenants/<tenant_id>`, the following actions occur: |
|
|
| - ✅ Tenant record is deleted |
| - ✅ All SAML configurations for the tenant are deleted |
| - ✅ All external identity records are deleted |
| - ⚠️ Users are preserved but unlinked from the tenant (their `tenant_id` is set to NULL) |
|
|
| **Example:** |
| ```bash |
| # Delete tenant with ID 5 |
| curl -X DELETE "$BASE_URL/api/saml/tenants/5" \ |
| -H "Authorization: Bearer $JWT_TOKEN" |
| ``` |
|
|
| **Response:** |
| ```json |
| { |
| "message": "Tenant acme-corp deleted successfully", |
| "users_affected": 5, |
| "saml_configs_deleted": 2 |
| } |
| ``` |
|
|
| ### Shell Scripts |
|
|
| Two convenience scripts are provided in the `scripts/` directory: |
|
|
| #### List Tenants |
|
|
| ```bash |
| # Make executable first |
| chmod +x scripts/list_tenants.sh |
| |
| # Usage |
| ./scripts/list_tenants.sh [API_URL] [USERNAME] [PASSWORD] |
| |
| # Examples |
| ./scripts/list_tenants.sh |
| ./scripts/list_tenants.sh http://localhost:5555 admin mypassword |
| ``` |
|
|
| The script displays a formatted table with tenant details and full JSON output. |
|
|
| #### Delete Tenant |
|
|
| ```bash |
| # Make executable first |
| chmod +x scripts/delete_tenant.sh |
| |
| # Usage |
| ./scripts/delete_tenant.sh <tenant_name_or_slug> [API_URL] [USERNAME] [PASSWORD] |
| |
| # Examples |
| ./scripts/delete_tenant.sh acme-corp |
| ./scripts/delete_tenant.sh "Acme Corporation" http://localhost:5555 admin mypassword |
| ``` |
|
|
| The script will: |
| 1. Authenticate with the API |
| 2. Search for the tenant by name or slug (case-insensitive) |
| 3. Display tenant information |
| 4. Ask for confirmation before deletion |
| 5. Delete the tenant and display the results |
|
|
| **Important:** Deletion is permanent and cannot be undone. Users are NOT deleted, only their tenant association is removed. |
|
|
| ### Testing Tenant Management |
|
|
| Run the automated test script to verify tenant management functionality: |
|
|
| ```bash |
| python3 scripts/test_tenant_management.py |
| ``` |
|
|
| This will test creating, listing, and deleting tenants, ensuring all operations work correctly. |
|
|
| ## Security Notes |
|
|
| - Always run the public endpoints over HTTPS. |
| - Keep `SAML_SP_PRIVATE_KEY` secret; rotate SP certificates on a schedule. |
| - Disable `allow_idp_initiated` if you require SP-initiated flows only. |
| - When deactivating accounts, set `User.is_active = False`; SAML logins will honor the flag. |
| - All tenant management operations require admin privileges and are logged for audit purposes. |
|
|
