Configure SAML 2.0 SSO for enterprise customers in HelloJohn Cloud. Okta, Azure AD, Google Workspace, and any SAML 2.0 identity provider.

SAML SSO lets enterprise customers sign in using their company's identity provider (IdP) — Okta, Azure Active Directory, Google Workspace, Ping Identity, and others.

SAML SSO is available on HelloJohn Cloud Enterprise only. It is not available in the self-hosted OSS build.

How SAML SSO works with HelloJohn

HelloJohn acts as the Service Provider (SP). Your customer's IT team configures their IdP to trust HelloJohn. When a user logs in:

1. User visits your app and clicks "Sign in with SSO"
2. Your app redirects to HelloJohn with the tenant ID
3. HelloJohn redirects to the customer's IdP (Okta, Azure AD, etc.)
4. User authenticates with their corporate credentials
5. IdP sends a SAML assertion back to HelloJohn
6. HelloJohn validates the assertion and creates/updates the user
7. HelloJohn issues access + refresh tokens
8. User is logged in to your app

From your app's perspective, SSO is transparent — you receive the same JWT regardless of whether the user authenticated with email/password or SAML SSO.

Setup

Step 1: Enable SSO for a tenant

PATCH /v2/admin/tenants/{tenantId}/auth/config
Authorization: Bearer $ADMIN_TOKEN
Content-Type: application/json

{
  "sso_enabled": true,
  "sso_required": false  // true = all users in this tenant must use SSO
}

Step 2: Get the SP metadata

HelloJohn generates SP metadata for each tenant:

GET /v2/admin/tenants/{tenantId}/sso/metadata

Returns XML with:

Entity ID: https://your-instance.hellojohn.dev/sso/{tenantId}
ACS URL: https://your-instance.hellojohn.dev/sso/{tenantId}/acs
SP Certificate: for IdP to verify requests

Step 3: Configure the IdP

In Okta Admin: Applications → Create App Integration → SAML 2.0
Single sign-on URL: https://your-instance.hellojohn.dev/sso/{tenantId}/acs
Audience URI (SP Entity ID): https://your-instance.hellojohn.dev/sso/{tenantId}
Name ID format: EmailAddress
Attribute statements:
- email → user.email
- first_name → user.firstName
- last_name → user.lastName
Download the IdP metadata XML from Okta

In Azure Portal: Enterprise Applications → New Application → Create your own
Select Integrate any other application you don't find in the gallery
Single sign-on method: SAML
Identifier (Entity ID): https://your-instance.hellojohn.dev/sso/{tenantId}
Reply URL (ACS URL): https://your-instance.hellojohn.dev/sso/{tenantId}/acs
Attributes & Claims:
- emailaddress → user.mail
- givenname → user.givenname
- surname → user.surname
Download the Federation Metadata XML

In Google Admin: Apps → Web and mobile apps → Add app → Add custom SAML app
ACS URL: https://your-instance.hellojohn.dev/sso/{tenantId}/acs
Entity ID: https://your-instance.hellojohn.dev/sso/{tenantId}
Name ID: Primary email, EMAIL format
Attribute mapping:
- email → Primary email
- first_name → First name
- last_name → Last name
Download the IdP metadata

Step 4: Upload IdP metadata to HelloJohn

POST /v2/admin/tenants/{tenantId}/sso/idp
Authorization: Bearer $ADMIN_TOKEN
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="metadata"; filename="idp-metadata.xml"
Content-Type: application/xml

{IdP metadata XML content}

Or upload the raw XML body:

POST /v2/admin/tenants/{tenantId}/sso/idp
Authorization: Bearer $ADMIN_TOKEN
Content-Type: application/xml

<?xml version="1.0"?>
<EntityDescriptor ...>
  ...
</EntityDescriptor>

Step 5: Test the SSO flow

# Get the SSO login URL for testing
GET /v2/admin/tenants/{tenantId}/sso/login-url

Open the URL in a browser and complete the SSO flow. HelloJohn validates the SAML assertion and logs the result.

Enforcing SSO

To require all users in a tenant to authenticate via SSO (block email/password login):

PATCH /v2/admin/tenants/{tenantId}/auth/config
{
  "sso_required": true
}

When sso_required is true:

Email/password login returns an error for users in this tenant
OAuth login is also blocked
Only SAML SSO is accepted

HelloJohn supports Just-In-Time (JIT) provisioning — when a user authenticates via SAML for the first time, HelloJohn automatically creates their account using the attributes from the SAML assertion.

SAML attribute	HelloJohn field
`NameID` (email format)	`email`
`email`	`email`
`first_name` / `givenName`	`first_name`
`last_name` / `surname`	`last_name`
`groups`	Used for role mapping (if configured)

Role mapping from SAML groups

Map IdP groups to HelloJohn roles:

PATCH /v2/admin/tenants/{tenantId}/sso/config
{
  "role_mappings": [
    { "saml_group": "IT-Admins", "role": "admin" },
    { "saml_group": "Developers", "role": "member" }
  ]
}

SCIM provisioning (Cloud Enterprise)

For automatic user lifecycle management (create, update, deactivate users based on your IdP), HelloJohn supports SCIM 2.0. Contact sales for SCIM setup.

Troubleshooting

Error	Cause	Fix
`invalid_signature`	SP and IdP certificates mismatch	Re-download SP metadata and re-configure IdP
`assertion_expired`	Clock skew > 5 minutes	Sync server clocks (NTP)
`invalid_acs_url`	ACS URL in IdP doesn't match	Must be `https://your-instance.hellojohn.dev/sso/{tenantId}/acs`
`missing_email_attribute`	IdP not sending email	Add `email` attribute mapping in IdP config
`user_not_provisioned`	JIT disabled + user doesn't exist	Enable JIT or pre-create the user

SAML SSO