> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.drimify.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Enterprise SSO - Configuration

# 🔐 Enterprise SSO – Complete Configuration Guide

Enterprise Single Sign-On (SSO) allows your organization to authenticate users into the **Drimify platform** using your existing Identity Provider (IdP). This is distinct from any SSO or authentication mechanisms used within games or experiences created on Drimify.

Users with your company domain can securely **log in to the Drimify platform** without creating separate passwords, and will automatically be assigned to the correct workspace.

||| Note: This guide covers platform access SSO only. If you are looking to configure authentication within a game or experience (e.g. gating game content behind a login), that is handled separately at the experience level.

This guide covers:

1. Available SSO protocols
2. OAuth 2.0 configuration
3. SAML 2.0 configuration
4. Default workspace assignment
5. Domain verification (DNS)
6. How platform login works
---

## 🚀 Available SSO Protocols

You can configure Enterprise SSO for platform login using one of the following protocols:

### 1️⃣ OAuth 2.0 (OpenID Connect)

Recommended for modern Identity Providers. Used by:

* Google
* Microsoft Entra ID
* Okta
* Custom OIDC providers

OAuth 2.0 relies on authorization flows and user info endpoints to retrieve user identity securely.

### 2️⃣ SAML 2.0

Widely used in enterprise environments. SAML uses XML-based authentication assertions exchanged between your Identity Provider and Drimify.

Choose the protocol supported by your Identity Provider.
---

## ⚙️ Creating a New SSO Configuration

Go to: **Admin → Enterprise SSO → New Configuration**

You will need to define:

* Configuration Name
* Email Domain
* SSO Protocol (OAuth 2.0 or SAML 2.0)

Once saved, domain verification will be required before enabling the SSO for platform login.

---

## 🌐 Email Domain

Enter the domain associated with your organisation. Example: [`company.com`](https://company.com/)

Users logging in **to the Drimify platform** with `@company.com` will automatically be redirected to your SSO provider.

Only one SSO configuration can be active per domain.

---

## 🟣 OAuth 2.0 Configuration

Select **OAuth 2.0** as the SSO protocol. You must create an OAuth / OpenID Connect application in your Identity Provider first.

### 🔁 Redirect URI (Required in your IdP)

When creating the OAuth application, configure this Redirect URI:
[__https://my.drimify.com/en/sso/callback/oauth__](https://my.drimify.com/en/sso/callback/oauth)

This URI must match exactly in your IdP configuration.

### 🔑 Client Credentials

* **Client ID** — Public identifier provided by your Identity Provider.
* **Client Secret** — Private key associated with your OAuth application. Keep it secure.

### 🌍 OAuth Endpoints

| Endpoint | Description | Example |
| ---- |
| Authorisation URL | Where users are redirected to log in | [`https://example.com/oauth/connect`](https://example.com/oauth/connect) |
| Access Token URL | Exchanges the auth code for an access token | [`https://example.com/oauth/token`](https://example.com/oauth/token) |
| Resource Owner URL | Returns user identity after authentication | [`https://example.com/oauth/userinfo`](https://example.com/oauth/userinfo) |

### 🎯 Scopes

Enter scopes as a comma-separated list. For standard OpenID Connect:
openid, profile, email

These allow access to: unique user ID, email address, first name, last name.

### 👤 Attribute Mapping

Your Identity Provider returns user data in JSON format. Define which fields map to required values:

| Field | Example value |
| ---- |
| ID Field | `sub` |
| Email Field | `email` |
| First Name Field | `given_name` |
| Last Name Field | `family_name` |

These field names must match exactly what your Identity Provider returns.

---

## 🔵 SAML 2.0 Configuration

Select **SAML 2.0** as the protocol. You will need the following values from your Identity Provider:

* **Identity Provider Entity ID (Issuer URL)** — Unique identifier of your IdP.
* **Single Sign-On Service URL** — The endpoint where authentication requests are sent.
* **Single Logout Service URL** *(Optional)* — Endpoint used for single logout.
* **X509 Certificate** — Public certificate used to validate SAML assertions.
* **Encryption X509 Certificate** *(Optional)* — Used if your provider requires encrypted assertions.
* **Requested Authentication Context** *(Optional)* — Defines required authentication strength (e.g. MFA). Leave disabled unless required.

### 🏢 Service Provider Information

After saving your SAML configuration, Drimify will generate values required by your Identity Provider:

* Service Provider Entity ID (Metadata URL)
* Assertion Consumer Service (ACS URL)
* Single Logout Service (SLS URL)

These must be added to your Identity Provider configuration.

---

## 🏢 Default Workspace Settings

Enterprise SSO allows automatic workspace assignment for all users logging in to the platform via SSO. You must define:

* **Workspace** — All users authenticating via this SSO will automatically join this workspace.
* **Default Department** — Users will be assigned to this department.
* **Predefined Role** — Defines the default permissions granted to new users on first platform login via SSO.

This ensures proper access control from the very first platform login.

---

## 🌍 Domain Verification (DNS Required)

After saving your SSO configuration, domain verification is mandatory before SSO can be activated for platform login.

To verify ownership:

1. A DNS TXT record will be generated.
2. Add the TXT record to your domain's DNS settings.
3. Click **"Verify Domain"** inside the platform.

Example record:
Type: TXT
Host: [__company.com__](https://company.com/)
Value: drimify-domain-verification=xxxxxxxxxxxxxxxx

DNS propagation may take **up to 48 hours**. SSO cannot be enabled until verification is successful.

---

## 🔁 How Platform Login Works

1. User navigates to the Drimify platform and enters their email address.
2. If the domain matches a configured SSO, they are automatically redirected to your Identity Provider.
3. After successful authentication, they are redirected back to Drimify.
4. If new, their **platform account** is created automatically and assigned to the configured workspace and role.

---

## 🧪 Testing Your SSO

Before enabling for all users:

* Test with a user from your domain
* Confirm email mapping works correctly
* Verify first and last names populate properly
* Test logout behaviour
* Ensure the redirect URI matches exactly

---

## ❗ Common Issues

**SSO response did not include an email address**
→ Ensure the email scope is included (OAuth) or the email attribute is mapped (SAML).

**Invalid redirect URI**
→ Confirm it matches exactly: [`https://my.drimify.com/en/sso/callback/oauth`](https://my.drimify.com/en/sso/callback/oauth)

**Domain not verified**
→ Ensure the DNS TXT record is correctly added and fully propagated.

---

## 🔐 Security Recommendations

* Never expose your Client Secret.
* Use HTTPS-only endpoints.
* Restrict your IdP application to your organisation.
* Regularly rotate credentials where possible.

---


|| Your Enterprise SSO for platform login is fully operational once the configuration is saved, the domain is verified, and SSO is enabled.