Abdulmuizz HamzatandRotimi Best
b599f1a017
* Update documentation for ClassroomIO: change Fumadocs to Blume, revise MDX format conventions, and clarify sidebar navigation requirements. * docs: update README and scripts for improved preview and error handling * docs: update Discord link in configuration and documentation * docs: add token-auth route and update documentation formatting * Fix formatting in auto-comment-issues.yml * Fix JSON syntax by adding a comma * fix(docs): declare Blume's Astro build deps so Cloudflare build resolves them blume build generates an Astro project under apps/docs/.blume/ that imports astro, @astrojs/mdx, @tailwindcss/vite, tailwindcss, @tailwindcss/typography, @shikijs/twoslash and @scalar/astro. Under pnpm's isolated node_modules these are nested inside blume and not resolvable from the docs app, so a clean --frozen-lockfile build (Cloudflare) fails at 'Cannot find module astro/config'. Declare them directly in @cio/docs, pinned to blume's resolved versions. * refactor(docs): update API reference paths and documentation for clarity * fix: change platofrm url to docs home page * Refactor documentation for self-hosting ClassroomIO - Removed the Supabase Cloud setup guide as it is no longer needed. - Updated the Enterprise SSO documentation to include a reference link for SSO & licensing. - Added new documentation for Content Security Policy (CSP) configuration. - Created a new section for configuring SMTP for email notifications. - Introduced a comprehensive configuration index for self-hosted ClassroomIO, detailing environment variables and their usage. - Added documentation for optional integrations including Google OAuth, OpenAI, and Unsplash. - Documented the generation and usage of required secrets for ClassroomIO. - Created a section for SSO & licensing, detailing the requirements for Enterprise features. - Added object storage configuration documentation, covering both bundled MinIO and external S3-compatible services. - Documented versioning and upgrade processes for ClassroomIO. - Updated the Coolify and Docker self-hosting guides to streamline configuration references and upgrade instructions. - Enhanced the Railway self-hosting guide with links to relevant configuration sections. - Updated token authentication documentation to reference SSO & licensing. * Add comprehensive guides for ClassroomIO features and functionalities - Introduced a new guide for the Student Dashboard, detailing navigation and features available to students. - Added a guide on using Tags for organizing and filtering courses within ClassroomIO. - Created a guide on how to take attendance in courses, including marking attendance and related functionalities. - Developed a Terminology guide to clarify key terms used throughout ClassroomIO. - Implemented a Token Auth guide for signing users into ClassroomIO from external applications using JWT. - Added instructions for using math in the editor with LaTeX support. - Created a guide for customizing the welcome email sent to students upon enrollment in courses. - Added a guide explaining what ClassroomIO is and its key features. - Updated the home documentation to provide a clearer overview of ClassroomIO and its resources. - Enhanced self-hosted configuration documentation with a new guide for deploying ClassroomIO on Dokploy. - Updated links in the self-hosted configuration documentation for better navigation. - Added new images to support the Dokploy deployment guide. - Updated asset packaging script to handle redirects for the new guide structure. - Fixed footer link to point to the correct Getting Started guide. * chore: uprage version * feat(docs): add DigitalOcean deployment guide and flatten guides structure - Add a guide for deploying ClassroomIO on DigitalOcean using Docker Compose and Caddy for automatic HTTPS. - List DigitalOcean as a deployment option in the self-hosting index. - Move guides out of content/docs/guides into content/docs (student-dashboard, tags, terminology, token-auth, what-is-classroomio, audience, cohorts, community, course, enterprise-sso, mcp, organization, quickstart/*). - Rename home.mdx to index.mdx. - Update package-assets script to emit redirects for the old guides paths. --------- Co-authored-by: Rotimi Best <best@classroomio.com>
199 lines
6.7 KiB
Plaintext
199 lines
6.7 KiB
Plaintext
---
|
|
title: Enterprise SSO
|
|
description: Configure Single Sign-On (SSO) with OIDC for your organization.
|
|
---
|
|
|
|
ClassroomIO supports Single Sign-On (SSO) via OpenID Connect (OIDC), allowing your organization members to sign in using your existing identity provider (IdP).
|
|
|
|
:::info[Enterprise Feature]
|
|
SSO requires an **Enterprise** plan.
|
|
|
|
**Cloud:** [Contact us](mailto:support@classroomio.com) to upgrade.
|
|
|
|
**Self-hosted:** Requires an Enterprise license key. If you are not using Enterprise-only features, you do not need a key.
|
|
[Book a call](http://cal.com/classroomio/enterprise) to get your license.
|
|
:::
|
|
|
|
:::note[Where to set `LICENSE_KEY` (self-hosted)]
|
|
Set `LICENSE_KEY` in the API service environment.
|
|
Local development: `apps/api/.env`.
|
|
Docker Compose: repository root `.env`.
|
|
If you do not use Enterprise-only features, leave `LICENSE_KEY` unset.
|
|
See [Self Hosting → SSO & licensing](/self-hosted/configuration/sso) for per-platform placement.
|
|
:::
|
|
|
|
## Supported Providers
|
|
|
|
We support OIDC-based SSO with the following identity providers:
|
|
|
|
- **Okta**
|
|
- **Google Workspace**
|
|
- **Auth0**
|
|
|
|
## How It Works
|
|
|
|
### Academy Login
|
|
When users visit your organization's custom domain (e.g., `yourorg.classroomio.com`), SSO is automatically detected and they can sign in directly with your IdP.
|
|
|
|
### Shared App Login
|
|
On the main ClassroomIO app (`app.classroomio.com`), users enter their email address first. If their email domain matches your configured SSO domain, they'll be prompted to sign in via SSO.
|
|
|
|
## Provider Setup Guides
|
|
|
|
### Google Workspace
|
|
|
|
1. **Create OAuth App in Google Cloud Console:**
|
|
- Go to [Google Cloud Console](https://console.cloud.google.com/)
|
|
- Navigate to **APIs & Services** → **Credentials**
|
|
- Click **Create Credentials** → **OAuth client ID**
|
|
- Configure the OAuth consent screen (choose "External" for testing)
|
|
- Create OAuth client ID:
|
|
- Application type: **Web application**
|
|
- Name: `ClassroomIO SSO`
|
|
- Authorized redirect URIs: (leave empty for now, you'll add this after Step 2)
|
|
|
|
2. **In ClassroomIO:**
|
|
- Go to **Settings** → **SSO**
|
|
- Select **Google Workspace**
|
|
- Fill in:
|
|
- **Issuer URL**: `https://accounts.google.com`
|
|
- **Email Domain**: Your workspace domain (e.g., `yourcompany.com`)
|
|
- **Client ID**: From Google Cloud Console
|
|
- **Client Secret**: From Google Cloud Console
|
|
- Click **Create Connection**
|
|
|
|
3. **Complete IdP Configuration:**
|
|
- Copy the **Callback URL** shown in ClassroomIO
|
|
- Go back to Google Cloud Console
|
|
- Edit your OAuth client and add the Callback URL to **Authorized redirect URIs**
|
|
- Save
|
|
|
|
4. **Activate** the connection in ClassroomIO
|
|
|
|
### Okta
|
|
|
|
1. **Create OIDC App in Okta Admin:**
|
|
- Go to Okta Admin Dashboard
|
|
- Navigate to **Applications** → **Create App Integration**
|
|
- Select **OIDC - OpenID Connect**
|
|
- Application type: **Web Application**
|
|
- Sign-in redirect URIs: (leave empty, you'll add after Step 2)
|
|
- Grant type: **Authorization Code**
|
|
|
|
2. **In ClassroomIO:**
|
|
- Go to **Settings** → **SSO**
|
|
- Select **Okta**
|
|
- Fill in:
|
|
- **Issuer URL**: Your Okta domain (e.g., `https://your-org.okta.com`)
|
|
- **Email Domain**: Your company domain
|
|
- **Client ID**: From Okta app
|
|
- **Client Secret**: From Okta app
|
|
- Click **Create Connection**
|
|
|
|
3. **Complete IdP Configuration:**
|
|
- Copy the **Callback URL** from ClassroomIO
|
|
- In Okta, edit your app and add the Callback URL to **Sign-in redirect URIs**
|
|
- Ensure these scopes are allowed: `openid`, `email`, `profile`
|
|
|
|
4. **Activate** the connection in ClassroomIO
|
|
|
|
### Auth0
|
|
|
|
1. **Create Application in Auth0:**
|
|
- Go to Auth0 Dashboard
|
|
- Navigate to **Applications** → **Create Application**
|
|
- Name: `ClassroomIO SSO`
|
|
- Type: **Regular Web Application**
|
|
- Allowed Callback URLs: (leave empty, add after Step 2)
|
|
|
|
2. **In ClassroomIO:**
|
|
- Go to **Settings** → **SSO**
|
|
- Select **Auth0**
|
|
- Fill in:
|
|
- **Issuer URL**: Your Auth0 domain (e.g., `https://your-tenant.auth0.com`)
|
|
- **Email Domain**: Your company domain
|
|
- **Client ID**: From Auth0 app
|
|
- **Client Secret**: From Auth0 app
|
|
- Click **Create Connection**
|
|
|
|
3. **Complete IdP Configuration:**
|
|
- Copy the **Callback URL** from ClassroomIO
|
|
- In Auth0, add the Callback URL to **Allowed Callback URLs**
|
|
- Ensure OIDC Conformant is enabled
|
|
|
|
4. **Activate** the connection in ClassroomIO
|
|
|
|
## Configuration Summary
|
|
|
|
Required scopes in all IdPs:
|
|
- `openid`
|
|
- `email`
|
|
- `profile`
|
|
|
|
## Access Policies
|
|
|
|
### Force SSO
|
|
When enabled, all users must sign in via SSO. Email/password login is disabled for your organization. This is recommended for security compliance.
|
|
|
|
### Auto-Join
|
|
When enabled, users who sign in via SSO with a matching email domain are automatically added to your organization. Otherwise, they must be invited first.
|
|
|
|
### Break-Glass Access
|
|
Allows organization admins to bypass SSO with email/password in case of emergency (e.g., IdP outage). Keep this enabled for safety.
|
|
|
|
## User Provisioning
|
|
|
|
### JIT (Just-In-Time) Provisioning
|
|
Users are automatically provisioned when they first sign in via SSO:
|
|
|
|
1. If the user has a pending invitation, they join with the invited role
|
|
2. If auto-join is enabled, they join with the default role (typically Student)
|
|
3. If neither, they can join later via invitation
|
|
|
|
### Role Mapping
|
|
Map IdP groups to ClassroomIO roles:
|
|
|
|
- Admins → `ROLE.ADMIN` (1)
|
|
- Tutors → `ROLE.TUTOR` (2)
|
|
- Students → `ROLE.STUDENT` (3)
|
|
|
|
Configure this in your SSO policy settings.
|
|
|
|
## Troubleshooting
|
|
|
|
### "Failed to register SSO provider"
|
|
- Verify your Issuer URL is correct and accessible
|
|
- Check that your IdP supports OIDC (not just SAML)
|
|
- Ensure the discovery endpoint exists at `{issuer}/.well-known/openid-configuration`
|
|
|
|
### "Callback URL mismatch"
|
|
- Copy the exact callback URL from the SSO settings page
|
|
- Ensure it matches exactly in your IdP configuration
|
|
|
|
### Users can't auto-join
|
|
- Verify the email domain matches exactly (e.g., `company.com` not `@company.com`)
|
|
- Check that "Auto-join" is enabled in your SSO policy
|
|
- Ensure the user has a verified email from your domain
|
|
|
|
## Security Notes
|
|
|
|
- SSO secrets (client credentials) are encrypted at rest
|
|
- All SSO login attempts are logged for audit purposes
|
|
- Force SSO is enforced server-side, not just UI-level
|
|
- Session management follows your IdP's policies
|
|
|
|
## SAML Support
|
|
|
|
SAML 2.0 support is planned for a future release. Currently, only OIDC is supported.
|
|
|
|
## API Reference
|
|
|
|
### Endpoints
|
|
|
|
- `GET /sso/discover?email=user@domain.com` - Check if email uses SSO
|
|
- `GET /sso/org/:orgId` - Get SSO info for an organization
|
|
- `POST /organization/sso` - Create SSO connection (Admin)
|
|
- `PUT /organization/sso/policy` - Update SSO policy (Admin)
|
|
|
|
See the [API documentation](/api) for full details.
|