# SSO Configuration
Set up Single Sign-On for your Vrex workspace
Single Sign-On (SSO) lets your team log in to Vrex using your organization's identity provider.

## Supported Providers

Vrex supports SSO via:

- **SAML 2.0** - Works with most enterprise IdPs
- **OpenID Connect (OIDC)** - For modern OAuth-based systems

### Common Identity Providers

| Provider | Protocol | Status |
|----------|----------|--------|
| Microsoft Entra ID (Azure AD) | SAML / OIDC | ✓ Supported |
| Okta | SAML / OIDC | ✓ Supported |
| Google Workspace | OIDC | ✓ Supported |
| OneLogin | SAML | ✓ Supported |
| Ping Identity | SAML | ✓ Supported |
| Other SAML 2.0 IdPs | SAML | ✓ Supported |

## Prerequisites

- Vrex workspace on a plan that supports SSO
- Admin access to your identity provider
- Domain ownership verification (for custom domains)

## Setup Process

### Step 1: Contact Vrex

SSO setup requires coordination. Email support@vrex.no with:

- Your workspace name
- Your identity provider
- Email domain(s) to enable SSO for
- Technical contact information

Our team will provide:
- Vrex SP metadata (for SAML)
- Callback URLs (for OIDC)
- Configuration guidance

### Step 2: Configure Your IdP

#### For Microsoft Entra ID (Azure AD)

1. Go to **Enterprise Applications** → **New Application**
2. Search for "Vrex" or create a custom application
3. Configure SAML settings:
   - **Entity ID:** `urn:auth0:vrex:<connection-name>`
   - **Reply URL:** `https://vrex.eu.auth0.com/login/callback`
4. Download the **Federation Metadata XML**
5. Send to Vrex support

#### For Okta

1. Go to **Applications** → **Add Application**
2. Select **SAML 2.0**
3. Configure:
   - **Single Sign-On URL:** `https://vrex.eu.auth0.com/login/callback`
   - **Audience URI:** `urn:auth0:vrex:<connection-name>`
4. Copy the **IdP metadata URL** or download metadata
5. Send to Vrex support

#### For Google Workspace

1. Go to **Admin Console** → **Apps** → **SAML Apps**
2. Click **Add App** → **Add custom SAML app**
3. Enter Vrex SAML configuration
4. Download **IdP metadata**
5. Send to Vrex support

### Step 3: Attribute Mapping

Map your IdP attributes to Vrex:

| Vrex Attribute | Common IdP Attribute |
|----------------|---------------------|
| `email` | user.email |
| `given_name` | user.firstName |
| `family_name` | user.lastName |
| `name` | user.displayName |

`email` is required. Name attributes are recommended.

### Step 4: User Provisioning

Choose how users are added to Vrex:

#### Just-in-Time (JIT) Provisioning

- Users are created automatically on first login
- No manual user management needed
- Default role assigned to new users

#### SCIM Provisioning

- Sync users automatically from your IdP
- User lifecycle managed by IdP
- Groups sync to Vrex teams
- Available for enterprise plans

### Step 5: Testing

Before enabling for all users:

1. Test with a pilot group
2. Verify login works
3. Check attribute mapping
4. Confirm provisioning behavior

### Step 6: Enforcement

Once tested, enable SSO enforcement:

- **Optional:** Users can choose SSO or password
- **Required:** All users must use SSO (recommended)

## User Experience

With SSO enabled:

1. User goes to Vrex login
2. Enters their email address
3. Redirected to company IdP
4. Authenticates with company credentials
5. Redirected back to Vrex, logged in

## Domain Verification

To enable SSO for `@company.com`:

1. Prove domain ownership via DNS TXT record
2. Add record: `vrex-verify=<verification-code>`
3. Vrex confirms domain ownership
4. SSO enabled for that domain

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "User not found" | Check JIT provisioning is enabled |
| Login loop | Verify callback URL in IdP |
| Wrong attributes | Check attribute mapping |
| Can't log in with password | SSO enforcement may be enabled |

## SSO and Existing Users

When enabling SSO for existing users:

- Accounts with matching email are linked automatically
- Users keep their project access
- Password login is disabled if enforcement is on

## Emergency Access

For SSO outages, keep a backup:

- Designated admin with password login
- Or contact Vrex support for temporary access