rtCloud supports three approaches for Single Sign-On (SSO):

OptionBest For
Embedded KeycloakOrganizations that want a fully self-contained SSO server bundled with rtCloud
External OIDC ProviderOrganizations already running an identity provider (Auth0, Authentik, Okta, Supabase, etc.)
Azure Active DirectoryOrganizations using Microsoft 365 or Azure AD

Without SSO configured, users log in with local rtCloud accounts managed through the admin panel.

Embedded Keycloak

The deployment includes an optional Keycloak container that runs alongside rtCloud. Keycloak is pre-configured with an rtSurvey realm and ready to use.

Requirements

  • A domain name with HTTPS (Keycloak requires HTTPS in production)
  • At least 4 GB RAM on the server (Keycloak adds ~512 MB memory usage)

Setup

1. Configure environment variables in .env:

  # Enable the embedded Keycloak container
EMBED_KEYCLOAK=true

# Keycloak URLs — use your actual domain
KEYCLOAK_URL=https://rtcloud.example.com/auth
KC_HOSTNAME=https://rtcloud.example.com/auth
KC_HOSTNAME_STRICT=false

# Realm and client settings (match the imported realm JSON)
KEYCLOAK_REALM=rtsurvey
KEYCLOAK_CLIENT_ID=rtsurvey-app
KEYCLOAK_CLIENT_SECRET=your-client-secret-here

# Keycloak admin credentials
KEYCLOAK_ADMIN_USER=admin
KEYCLOAK_ADMIN_PASSWORD=change_me_keycloak_admin_password

# Keycloak database (created automatically)
KEYCLOAK_DB=keycloak
KEYCLOAK_DB_USER=keycloak
KEYCLOAK_DB_PASSWORD=change_me_keycloak_db_password

# Port Keycloak listens on (host-side, proxied by Nginx)
KEYCLOAK_PORT=8091

2. Start with the embedded Keycloak profile:

  docker compose -f docker-compose.production.yml --profile embed-keycloak up -d

3. Verify Keycloak is healthy:

  docker compose -f docker-compose.production.yml ps

The rtcloud-keycloak container should show Up (healthy) after 2–3 minutes.

4. Access the Keycloak admin console:

  https://rtcloud.example.com/auth/admin

Log in with KEYCLOAK_ADMIN_USER and KEYCLOAK_ADMIN_PASSWORD.

What Is Pre-Configured

The embedded Keycloak starts with a pre-imported rtsurvey realm that includes:

  • Client configuration for the web application
  • Default user roles (admin, project_manager, enumerator, analyst)
  • Session and token settings optimized for rtSurvey

You can add users directly in the Keycloak admin console or connect Keycloak to an upstream identity provider (LDAP, SAML).

Nginx Routing

When using the cloud deployment scripts, Nginx is configured to proxy both services:

PathBackend
/rtCloud app on 127.0.0.1:8080
/auth/Keycloak on 127.0.0.1:8090

External OIDC Provider

Connect rtCloud to any OpenID Connect-compatible identity provider. This approach does not require the Keycloak container.

Supported Providers

Any OIDC-compliant provider works, including:

  • Authentik
  • Auth0
  • Okta
  • Keycloak (external instance)
  • Supabase
  • Google (for Google Workspace organizations)
  • GitHub (via OAuth apps with OIDC extension)

Setup

1. Register rtCloud as an OIDC client in your identity provider.

You will need:

  • A client ID and client secret
  • To register the redirect URI: https://rtcloud.example.com/auth/callback
  • For mobile app support, also register: vn.rta.rtsurvey.auth://callback

2. Configure environment variables in .env:

  # OIDC discovery URL (provider-specific — check your IdP documentation)
OIDC_ISSUER_URL=https://your-identity-provider.com

# Client credentials from your identity provider
OIDC_CLIENT_ID=rtcloud-app
OIDC_CLIENT_SECRET=your-client-secret-here

# Scopes to request (openid, profile, and email are typically sufficient)
OIDC_SCOPE=openid profile email

# Redirect URI registered in your identity provider
OIDC_REDIRECT_URI=https://rtcloud.example.com/auth/callback

# Optional: separate mobile app client
OIDC_MOBILE_CLIENT_ID=rtcloud-mobile
OIDC_MOBILE_REDIRECT_URI=vn.rta.rtsurvey.auth://callback

# Set to true to auto-create rtCloud accounts for new OIDC users
OPEN_REGISTRATION=false

3. Restart the app container to apply the changes:

  docker compose -f docker-compose.production.yml up -d --force-recreate rtcloud

Auto-Provisioning Users

When OPEN_REGISTRATION=true, rtCloud automatically creates a local account the first time a user signs in via OIDC. The account is populated with the user’s name and email from the ID token.

When OPEN_REGISTRATION=false (default), an rtCloud administrator must create the user account first, and the OIDC identity is linked on first login.

Custom Endpoints

If your provider does not support OIDC discovery (.well-known/openid-configuration), you can set endpoints manually:

  OIDC_AUTHORIZATION_ENDPOINT=https://your-provider.com/oauth2/authorize
OIDC_TOKEN_ENDPOINT=https://your-provider.com/oauth2/token
OIDC_USERINFO_ENDPOINT=https://your-provider.com/oauth2/userinfo

Azure Active Directory

Integrate rtCloud with your organization’s Microsoft Azure AD tenant.

Setup

1. Register a new app in the Azure Portal:

  • Go to Azure Active Directory → App registrations → New registration
  • Name: rtCloud
  • Redirect URI: https://rtcloud.example.com/auth/callback (Web type)
  • After creation, note the Application (client) ID and Directory (tenant) ID
  • Under Certificates & secrets, create a new client secret

2. Configure environment variables in .env:

  AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

3. Restart the app container:

  docker compose -f docker-compose.production.yml up -d --force-recreate rtcloud

Users in your Azure AD tenant can now log in to rtCloud using their Microsoft credentials.

Disabling SSO

To revert to local authentication, remove or comment out all SSO-related variables from .env, then restart the app container:

  docker compose -f docker-compose.production.yml up -d --force-recreate rtcloud

If you were using embedded Keycloak, stop it by omitting the --profile embed-keycloak flag and running docker compose down followed by up -d without the profile.

Was this page helpful?