SSO/SAML
SSO/SAML
Configure Single Sign-On for your organization.
Overview
SSO allows users to authenticate using your identity provider instead of passwords.
Supported Providers
| Provider | Protocol | Setup Complexity |
|---|---|---|
| Okta | SAML 2.0, OIDC | Easy |
| Azure AD | SAML 2.0, OIDC | Easy |
| Google Workspace | OIDC | Very Easy |
| OneLogin | SAML 2.0 | Medium |
| Generic SAML | SAML 2.0 | Variable |
Setting Up SSO
Prerequisites
- Admin access in Karolina
- Admin access in your IdP
- SSL certificate for callback URL
Step 1: Configure in Karolina
- Go to Settings → Security → SSO
- Click Configure SSO
- Select provider type
- Copy Service Provider details
Step 2: Configure in IdP
Create application/connection:
| Setting | Value |
|---|---|
| Entity ID | https://karolina.ai/saml/{org-id} |
| ACS URL | https://karolina.ai/api/auth/saml/callback |
| SLO URL | https://karolina.ai/api/auth/saml/slo |
Step 3: Configure Attributes
Map SAML attributes:
| SAML Attribute | Maps To |
|---|---|
email |
Email address |
firstName |
First name |
lastName |
Last name |
groups |
Role/group mapping |
Step 4: Test Connection
- Click Test Connection
- Redirects to IdP
- Authenticate
- Returns to Karolina
- Verify success
Step 5: Enable SSO
- Review configuration
- Click Enable SSO
- Users now authenticate via SSO
SAML Configuration
Manual SAML Setup
For custom implementations:
<EntityDescriptor entityID="https://karolina.ai">
<SPSSODescriptor>
<AssertionConsumerService
URL="https://karolina.ai/api/auth/saml/callback"
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
</SPSSODescriptor>
</EntityDescriptor>Attribute Mapping
| Attribute | Required | Description |
|---|---|---|
email |
Yes | User email (unique identifier) |
firstName |
Yes | First name |
lastName |
Yes | Last name |
groups |
No | Group memberships |
department |
No | Department |
Group Mapping
Map IdP groups to Karolina roles:
| IdP Group | Karolina Role |
|---|---|
CS-Admins |
Admin |
CS-Managers |
Manager |
CS-Team |
CSM |
CS-Viewers |
Viewer |
OIDC Configuration
For Google Workspace
- Create OAuth 2.0 client in Google Cloud
- Add authorized redirect URI
- Copy Client ID and Secret
- Enter in Karolina
For Azure AD
- Register application in Azure
- Configure API permissions
- Copy Client ID and Secret
- Enter in Karolina
SSO Behavior
User Login Flow
- User visits Karolina
- Redirected to SSO login
- User authenticates with IdP
- IdP redirects back to Karolina
- User logged in
JIT Provisioning
Auto-create users on first SSO login:
- Enable Just-In-Time Provisioning
- First login creates Karolina account
- User assigned default role
- Admin can adjust role
Just-In-Time Options
| Option | Behavior |
|---|---|
| Auto-create | Create new users automatically |
| Require pre-creation | Admin must create first |
| Match by email | Match to existing user |
SSO Settings
Enforcement
| Setting | Description |
|---|---|
| Optional SSO | Users choose login method |
| Required SSO | Only SSO login allowed |
| Password allowed | Backup for SSO issues |
Session Settings
| Setting | Default | Description |
|---|---|---|
| Session Duration | 8 hours | How long before re-auth |
| Idle Timeout | 30 min | Inactivity logout |
Troubleshooting
| Issue | Solution |
|---|---|
| Redirect loop | Check callback URL |
| User not found | Check JIT provisioning |
| Group not mapping | Verify group names |
| Cert error | Update IdP certificate |
| Slow login | Check IdP performance |
Security
Certificate Rotation
Rotate signing certificates:
- Add new certificate in IdP
- Add new certificate in Karolina
- Test with new cert
- Remove old certificate
Audit Logs
Track SSO events:
- Login attempts
- Failures
- New user creation
- Role changes