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 (config.yaml)

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

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. Dashboard displays PostgreSQL credentials and JWT token

Using Credentials

PostgreSQL:

psql -h your-domain.com -p 5432 -U john.doe@company.com -d boilstream

HTTP Ingestion (JWT):

fetch('https://your-domain.com/ingest/events', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${JWT_TOKEN}`,  // From dashboard
    'Content-Type': 'application/vnd.apache.arrow.stream'
  },
  body: arrowData
});

Troubleshooting

SAML button not showing: Check provider is Enabled in superadmin GUI, restart BoilStream

"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 certificate expiration in Azure Portal (auto-rotates)
• 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

• GitHub OAuth - Configure GitHub authentication
• Google OAuth - Configure Google authentication
• Complete Web Auth Guide