Skip to main content

SSO Integration Guide

Siter supports two SSO integration methods:

  • Microsoft Entra ID (Azure AD) — for organizations using Azure AD, including GCC High and DoD clouds
  • Active Directory (LDAP) — for on-premises Active Directory environments, including air-gapped networks with no internet connectivity

Select the section that matches your organization's identity provider.

Microsoft Entra ID (Azure AD)​

Prerequisites​

  • Azure AD Administrator access in your GCC High or DoD tenant
  • Siter environment URLs for redirect URIs (provided by Siter team)

Step 1: Access Azure Portal​

Navigate to the appropriate Azure portal for your cloud environment:

Cloud TypePortal URL
GCC Highhttps://portal.azure.us
DoDhttps://portal.azure.us
Commercialhttps://portal.azure.com

Step 2: Create App Registration​

  1. In the Azure Portal, go to Microsoft Entra ID (or search for "Entra" in the top search bar)
  2. In the left sidebar, click App registrations
  3. Click + New registration
  4. Fill in the registration form:
FieldValue
NameSiter SSO Integration (or your preference)
Supported account typesSelect "Accounts in this organizational directory only"
Redirect URILeave blank for now (we'll add it in the next step)
  1. Click Register

Step 3: Configure Authentication​

  1. In your new App Registration, click Authentication in the left sidebar

  2. Click + Add a platform

  3. Select Single-page application

  4. Add the redirect URIs provided by Siter. Typical values:

    https://siter.app

    Note: Add all environment URLs provided by the Siter team. The URI must match exactly (including https://, no trailing slash).

  5. Scroll down to Implicit grant and hybrid flows

  6. Check the box for ID tokens (used for implicit and hybrid flows)

  7. Click Save

Step 4: Configure API Permissions​

  1. Click API permissions in the left sidebar
  2. Click + Add a permission
  3. Select Microsoft Graph
  4. Select Delegated permissions
  5. Search for User.Read and check the box
  6. Click Add permissions
  1. Click Grant admin consent for [Your Organization Name]
  2. Click Yes to confirm

Why grant admin consent? Government tenants typically disable user self-consent. Without admin consent, users will see an error when trying to sign in:

"AADSTS65001: The user or administrator has not consented to use the application."

Granting admin consent pre-approves the permission for all users in your organization.

Note: User.Read is the only permission required. Siter extracts user information from standard token claims.

Step 5: Collect Information for Siter​

Go to Overview in the left sidebar and copy these values:

FieldWhere to Find It
Application (client) IDDisplayed on the Overview page
Directory (tenant) IDDisplayed on the Overview page

Also note your organization's email domains (e.g., @agency.gov, @agency.mil).

Step 6: Provide Information to Siter​

Send the following to your Siter administrator:

Organization Name: [Your organization's name]
Cloud Type: [GCC High / DoD]
Tenant ID: [Directory (tenant) ID from Step 5]
Client ID: [Application (client) ID from Step 5]
Email Domains: [Comma-separated list, e.g., agency.gov, agency.mil]

The Siter team will configure the SSO integration and notify you when it's ready for testing.

Step 7: Test the Integration​

Once Siter confirms the configuration is complete:

  1. Open Siter in your browser
  2. Click Sign in with Microsoft
  3. Enter your organization email address (e.g., user@agency.gov)
  4. You should be redirected to your organization's Azure AD login page
  5. Sign in with your credentials
  6. You should be returned to Siter, now logged in

Troubleshooting​

"The redirect URI is not valid" or "AADSTS50011: The reply URL does not match"​

Cause: The redirect URI in your App Registration doesn't match Siter's URL.

Solution:

  • Go to Authentication in your App Registration
  • Verify the redirect URI matches exactly what Siter provided
  • Check for typos, missing https://, or trailing slashes
  • Click Save after making changes

"AADSTS65001: The user or administrator has not consented"​

Cause: Admin consent has not been granted for the application.

Solution:

  • Go to API permissions in your App Registration
  • Click Grant admin consent for [Your Organization]
  • Wait a few minutes for the change to propagate

"Unable to find tenant" or "AADSTS90002: Tenant not found"​

Cause: Wrong Azure portal or incorrect tenant ID.

Solution:

"ID tokens not enabled" or token errors​

Cause: ID tokens are not enabled in the App Registration.

Solution:

  • Go to Authentication in your App Registration
  • Under Implicit grant and hybrid flows, check ID tokens
  • Click Save

User email not found after sign-in​

Cause: The token doesn't contain the user's email address.

Solution:

  • Ensure User.Read permission is granted
  • Grant admin consent if not already done
  • The system will fall back to preferred_username claim if email is not present

Security Notes​

  • Client ID and Tenant ID are not secrets - They are public identifiers and safe to share
  • No client secret is required - Siter uses the authorization code flow with PKCE, which doesn't require a client secret for single-page applications
  • Minimal permissions - Siter only requests User.Read to access basic profile information

Active Directory (LDAP)​

Active Directory authentication allows users to sign in with their on-premises AD credentials (email and password). This works without internet connectivity, making it suitable for air-gapped and classified environments.

Prerequisites​

  • An Active Directory domain controller accessible from the Siter API server
  • LDAPS (port 636) enabled on the domain controller (recommended)
  • The domain controller's CA root certificate, if using an internal CA

How It Works​

When a user signs in with Active Directory:

  1. The user enters their email address and password in Siter
  2. Siter extracts the email domain and looks up the SSO configuration
  3. Siter performs an LDAP Direct Bind against the configured domain controller using the user's credentials
  4. On success, Siter retrieves the user's AD attributes (objectGUID, email, display name) and issues a session token
  5. The user's password is never stored or logged — it is only used for the LDAP bind

Step 1: Gather Information​

Collect the following from your AD administrator:

InformationExampleDescription
Domain controller hostnamedc01.corp.example.comThe FQDN or IP address of the AD domain controller
LDAPS port636Typically 636 for LDAPS or 389 for plain LDAP
Email domainscorp.example.comThe email domain(s) used by your organization
UPN suffix (if different from email)corp.localOnly needed if the AD User Principal Name differs from the email domain
CA root certificateca-root.crtThe root certificate of the CA that issued the domain controller's TLS certificate

Step 2: Provide Information to Siter​

Send the following to your Siter administrator:

Organization Name: [Your organization's name]
SSO Type: Active Directory
LDAP Server: [Domain controller hostname]
LDAP Port: [636]
Use SSL: [Yes]
UPN Suffix: [Leave blank unless AD UPN differs from email domain]
Email Domains: [Comma-separated list, e.g., corp.example.com]
CA Root Certificate: [Attach the .crt file]

The Siter administrator will:

  1. Mount the CA root certificate in the API container
  2. Configure the SSO integration in the Admin dashboard
  3. Notify you when it's ready for testing

Step 3: Test the Integration​

Once the Siter administrator confirms the configuration:

  1. Open Siter in your browser
  2. Click Sign in with Active Directory
  3. Enter your full email address (e.g., user@corp.example.com)
  4. Enter your AD password
  5. You should be signed in to Siter

Troubleshooting​

"Directory service unavailable"​

Cause: The Siter API cannot reach the domain controller.

Solution:

  • Verify the domain controller hostname and port are correct in the SSO configuration
  • Confirm the domain controller is reachable from the Siter API server (check firewalls, DNS, and network routes)
  • Use the Test Connection button in Admin > SSO Integrations to verify connectivity

"Could not establish a secure connection to the directory server"​

Cause: The Siter API does not trust the domain controller's TLS certificate.

Solution:

  • Ensure the CA root certificate is volume-mounted into the API container
  • Verify update-ca-certificates runs in the container entrypoint
  • Confirm the certificate file is in PEM format (.crt extension)

"The directory server requires a secure (SSL/TLS) connection"​

Cause: The SSO configuration has SSL disabled, but the domain controller requires encrypted connections.

Solution:

  • Enable Use SSL/TLS in the SSO configuration
  • Ensure the LDAP port is set to 636 (LDAPS)

"Invalid email or password"​

Cause: The credentials are incorrect, or the UPN doesn't match what AD expects.

Solution:

  • Verify the user can sign in to other AD-integrated services with the same credentials
  • If the AD UPN suffix differs from the email domain (e.g., AD uses user@corp.local but email is user@company.com), set the UPN Suffix field in the SSO configuration

"Account is locked" / "Account is disabled"​

Cause: The AD account has been locked out or disabled by an administrator.

Solution:

  • Contact your AD administrator to unlock or re-enable the account

Security Notes​

  • Passwords are never stored — Siter uses the password only for the LDAP bind and discards it immediately
  • LDAPS is strongly recommended — Without TLS, credentials are transmitted in plaintext over the network
  • No service account required — Siter uses Direct Bind authentication, where the user's own credentials are used to connect to AD. No privileged service account is needed
  • Minimal AD access — After authentication, Siter only reads the user's own attributes (objectGUID, email, display name). No directory-wide queries are performed

Support​

If you encounter issues not covered in this guide, contact your Siter administrator with:

  1. The exact error message you're seeing
  2. Screenshots if available
  3. The email domain you're trying to sign in with