Skip to main content
Internal only. This page is for Juno support staff. For user-facing guidance, see Login Issues.

​
SSO architecture overview

Juno supports SAML 2.0 SSO via Firebase Authentication’s SAML provider. The flow: 
User → Juno login page → Firebase SAML redirect → Customer IdP (Okta, Azure AD, etc.)
     → SAML assertion → Firebase validates → Juno issues JWT → User lands on home
SAML config lives in the tenant’s auth configuration in Firebase (tenantId scoped).

​
SAML config fields

Found in Admin → Integrations → SSO (visible to Super Admins only):
FieldDescriptionCommon mistake
entryPointIdP SSO URL (where Firebase sends the auth request)Trailing slash or wrong URL from IdP metadata
certIdP signing certificate (PEM, without headers)Expired cert, headers included, or copied with whitespace
issuerSP entity ID (Juno’s identifier, sent to IdP)Must match exactly what’s configured in IdP
callbackUrlACS URL (where IdP sends the SAML assertion back)Must be the Firebase auth handler URL for this tenant
logoutUrlIdP logout URL (optional)Wrong URL causes broken logout, not login failure
attributesMappingMaps IdP attributes → Juno fieldsMismatch here = user created with wrong email/name

​
Diagnosis flow

​
Step 1 — Enable SAML assertion logging

In the tenant’s Firebase configuration, temporarily enable: 
TenantAuth.saml.logProfile = true
This logs the full SAML assertion to Firebase logs. Check Firebase → Logs → Authentication after the user attempts login.

​
Step 2 — Check the SAML assertion

In the log output, confirm:
  • The assertion is being received (if nothing logged → assertion never reached Firebase)
  • NameID or the mapped email attribute is present and correct
  • The assertion is not expired (NotOnOrAfter timestamp)
  • The signing certificate in the assertion matches the cert in Juno’s config

​
Step 3 — Check attribute mapping

The attributesMapping must map IdP attributes to Juno’s expected fields: 
{
  "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
  "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
  "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
}
The left side is Juno’s field name; the right side is the IdP attribute URI. If the IdP uses a different attribute URI (common with Azure AD vs. Okta), the mapping must be updated.

​
Step 4 — Check the tenant ID

The tenant ID in Juno’s SSO config must exactly match the Firebase tenant ID and the org slug in MongoDB. A mismatch causes Firebase to reject the SAML response. 
Admin → Settings → Tenant Info → Tenant ID (slug)
Firebase console → Authentication → Providers → SAML → Tenant ID

​
Common failure modes

​
A: User redirected to IdP, then returned to error page

Likely cause: Certificate mismatch or expired certificate.
  1. Download the current IdP metadata XML
  2. Extract the signing certificate
  3. Compare with what’s in Juno’s SAML cert field (strip PEM headers before comparing)
  4. Update Juno’s cert field if different

​
B: Login succeeds but user has wrong name/email in Juno

Likely cause: attributesMapping misconfigured.
  1. Enable logProfile = true and attempt login
  2. In the SAML assertion log, find the actual attribute URIs for email, first name, last name
  3. Update attributesMapping in Juno to match the actual URIs

​
C: Some users log in fine; others get errors

Likely cause: IdP is not provisioning all users in the same way, or some users have non-standard attribute values (e.g. missing first name).
  1. Compare a working user’s SAML assertion with a failing user’s
  2. Look for missing or differently-formatted attributes
  3. Adjust attribute mapping or coordinate with customer’s IdP admin

​
D: SSO was working, suddenly stopped

Most likely causes:
  1. IdP signing certificate expired → customer needs to update cert in their IdP and provide new cert to Juno
  2. Customer changed IdP configuration without notifying Juno → request updated metadata
  3. Firebase tenant got a config update that wiped the SAML settings → restore from backup or re-enter

​
Email domain auto-signup

If the tenant has allowedEmailDomains configured, any user with a matching email domain who successfully authenticates via SSO is automatically provisioned in Juno with the default role (Learner). This means: a misconfigured SAML attribute mapping that maps a non-email value to the email field can create corrupt user records. Check for junk user accounts if this is suspected.

​
Disable SSO (emergency)

If SSO is completely broken and an admin needs access:
  1. Super Admin or Juno support (level 3+) can disable SAML provider in Firebase for the tenant
  2. Admins can then log in via email/password temporarily
  3. Fix the SAML config, re-enable, test with a non-admin account first before re-enabling for all users
Last modified on March 26, 2026