Entra ID SAML SSO

Configure Microsoft Entra ID SAML Single Sign-On via BoilStream's built-in Superadmin Dashboard at https://your-domain/auth.

Prerequisites

• Microsoft Entra ID tenant
• Global Administrator or Application Administrator role
• BoilStream with HTTPS enabled
• Superadmin access to BoilStream

Step 1: Create Enterprise Application

1. Azure Portal → Entra ID → Enterprise applications
2. New application → Create your own application
3. Name: BoilStream Authentication
4. Type: Non-gallery application
5. Click Create

Step 2: Configure SAML

Basic SAML Configuration

Field	Value
Identifier (Entity ID)	https://your-domain.com/auth/saml/metadata
Reply URL	https://your-domain.com/auth/saml/acs
Sign on URL	https://your-domain.com/auth
Logout URL	https://your-domain.com/auth/saml/logout

Attributes & Claims

Configure these claims:

Claim	Source Attribute
Name ID	user.mail
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	user.mail
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	user.userprincipalname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	user.givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	user.surname
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups	user.groups

Add group claim:

1. Add a group claim → Security groups
2. Source: Group ID (recommended)

Download Metadata

SAML Signing Certificate section → Download Federation Metadata XML

Step 3: Assign Users

1. Enterprise Application → Users and groups
2. Add user/group → Select users/groups
3. Click Assign

For RBAC, create security groups:

• BoilStream Admins - Full access
• BoilStream Data Engineers - Write access
• BoilStream Analysts - Read-only

Note Group Object IDs from Entra ID → Groups for authorization config.

Step 4: Configure BoilStream

Via Superadmin GUI

1. Login as superadmin at https://your-domain.com/auth (username: boilstream)
2. Navigate to SAML Providers
3. Click Add SAML Provider
4. Fill provider details:
   • Name: Entra ID
   • SP Entity ID: https://your-domain.com/auth/saml/metadata
   • ACS URL: https://your-domain.com/auth/saml/acs
   • SLO URL: https://your-domain.com/auth/saml/logout (optional)
5. Upload IdP Metadata → Select downloaded XML file
6. Verify attribute mappings (pre-filled with Microsoft defaults)
7. Toggle Enabled → Save

Single Provider

BoilStream supports one SAML provider at a time. Delete existing provider before adding a new one.

Authorization

Merge these supported fields into your generated configuration. They configure protocol group checks; catalog ownership, membership and grants still control access to data.

auth:
  authorization_enabled: true
  admin_groups:
    - "12345678-1234-1234-1234-123456789abc"  # Group Object ID
  read_only_groups:
    - "34567890-3456-3456-3456-345678901cde"

For a write group, set the server environment variable WRITE_GROUPS to a comma-separated list of group IDs. There is no auth.write_groups YAML field. See Catalog access modes for the separate catalog permissions.

Step 5: Test

1. Logout from superadmin
2. Navigate to https://your-domain.com/auth
3. Click Sign in with Entra ID
4. Authenticate with Microsoft credentials
5. Open the dashboard to obtain credentials for your authorized catalogs and topics

Using Credentials

SAML signs you in to the dashboard. Use the credentials issued for the interface you intend to connect to:

• PGWire: obtain temporary database credentials and use the returned host, port, catalog and trusted TLS certificate. See PostgreSQL credentials.
• HTTP Arrow: create an ingest token for the target topic and send binary Arrow IPC to /ingest/TOKEN. Follow the HTTP upload example and check the admitted row count. A dashboard JWT is not a replacement for the scoped ingest token.
• Native DuckDB: follow the managed attachment workflow.

Troubleshooting

SAML button not showing: Check the provider is Enabled in the superadmin GUI, then reload the login page

"SAML Response validation failed": Re-download/upload Federation Metadata XML from Azure Portal

"User not authorized": Verify user is in assigned groups, check admin_groups in config match Group Object IDs

"Redirect URI mismatch": Verify Reply URL in Azure Portal exactly matches ACS URL

Groups not in SAML response: Verify group claim configured in Attributes & Claims, check user is group member

Security Best Practices

• Monitor signing-certificate expiry and update the configured metadata when certificates change
• Use Group Object IDs (stable) vs names (breaks on rename)
• Enable MFA in Entra ID for admin accounts
• Use short session TTLs (default: 8 hours)
• Enable Conditional Access policies

Managing SAML Config

Update: Superadmin GUI → SAML Providers → Click provider → Edit → Save

Delete: SAML Providers → Click provider → Delete → Confirm

Changes apply immediately without restart.

Next Steps

• Authorization and catalog grants
• Credential types
• Complete Web Auth Guide