Connect Microsoft Entra ID

operations

TL;DR

Administrators can configure Microsoft Entra ID as the SAML identity provider for dashboard sign-in. Match the entity and reply URLs, import the provider metadata and test an assigned account. SAML authenticates the user; product groups and catalog permissions still determine which operations and data the user can access.

Message sequenceFederated sign-in establishes identity, then access is checked

Federation proves identity. Catalog permissions still determine which data the user can access.

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

Azure Portal → Entra ID → Enterprise applications
New application → Create your own application
Name: BoilStream Authentication
Type: Non-gallery application
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:

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

Download metadata

SAML Signing Certificate section → Download Federation Metadata XML

Step 3: assign users

Enterprise Application → Users and groups
Add user/group → Select users/groups
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

Login as superadmin at https://your-domain.com/auth (username: boilstream)
Navigate to SAML Providers
Click Add SAML Provider
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)
Upload IdP Metadata → Select downloaded XML file
Verify attribute mappings (pre-filled with Microsoft defaults)
Toggle Enabled → Save

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

Logout from superadmin
Navigate to https://your-domain.com/auth
Click Sign in with Entra ID
Authenticate with Microsoft credentials
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.