Sentry & Keycloak SAML2 Integration

This guide explains how to integrate Keycloak (as Identity Provider) with Sentry (as Service Provider) using SAML2 authentication, for secure and controlled Single Sign-On (SSO) within the TechFinite infrastructure.

🔧 Prerequisites

• ✅ Keycloak server running at https://keycloak.techfinite.com

• ✅ Sentry (self-hosted) running at https://sentry.techfinite.com

• ✅ Admin access to both systems

• ✅ Docker & Docker Compose set up for Sentry

🛠️ Step 1: Create SAML Client in Keycloak

1. Login to Keycloak Admin Console.

2. Navigate to your Realm → Clients → Create.

3. Set:

   • Client ID: https://<sentry-host>/saml/metadata/<org-slug name>/

   • Client Protocol: saml

4. Click Save.

Client Settings:

🧩 Step 2: Setup Attribute Mapper in Keycloak

1. Delete default "role list" mapper.

2. Go to Mappers → Add Builtin → X500 Email.

3. Edit the new mapper:

   • SAML Attribute Name: user_email

🎯 Step 3: Configure SAML2 in Sentry

1. Open Sentry web UI → Organization Settings → Auth → SAML2.

2. Use Metadata URL:

   ruby
   https://<Keycloak-host>/realms/<realm-name>/protocol/saml/descriptor

3. Set Attribute Mappings:

   • IdP User ID: user_email

   • User Email: user_email

⚙️ Step 4: Configure Sentry Server (.env + sentry.conf.py)

Edit .env in ~/self-hosted/:

env
SENTRY_SSO_DEFAULT_LOGIN=false 
SENTRY_SSO_AUTO_LINK=false

Edit /etc/sentry/sentry.conf.py inside the container:

bash
docker compose exec web bash 
echo "SENTRY_FEATURES['auth:register'] = False" >> /etc/sentry/sentry.conf.py

Optional (for password login backup):

python
SENTRY_FEATURES['auth:login'] = True

Then restart:

bash
docker compose restart web

🧪 Step 5: Testing

✅ Expected

🧨 Common Errors & Fixes