Single sign-on (SAML + SCIM)
EnterpriseSign in to Hjarni with your work account through Okta, Microsoft Entra, Auth0, OneLogin, or any SAML 2.0 IdP. Sync users automatically with SCIM (optional).
Overview
Hjarni implements SAML 2.0 for login. Your IdP authenticates the user. Hjarni trusts the signed assertion.
SCIM 2.0 is optional for provisioning. Your IdP pushes user create, update, and deactivate calls to Hjarni. Accounts stay in sync without anyone logging in first.
SSO is configured per team. Enable it for one team and leave others on password, Google, GitHub, or Apple login. Or require SSO for everyone on a team.
Requirements
- Plan
- Enterprise. Contact us to enable on your team.
- IdP
- Any SAML 2.0 provider: Okta, Microsoft Entra, Auth0, OneLogin, Google Workspace, Ping, JumpCloud, and more.
- Role on Hjarni
- Team owner. SSO and SCIM settings live under team settings and are owner-only.
- Bindings
- HTTP-Redirect for SP-initiated AuthnRequest; HTTP-POST for the IdP's assertion back to Hjarni.
Configure your IdP
In your IdP, create a new SAML 2.0 application using the service-provider details below. Replace <team_id> with the numeric ID of your Hjarni team (visible in the address bar when you open Team settings > SSO).
- Assertion Consumer Service URL
-
https://hjarni.com/auth/saml/<team_id>/callback
Okta calls this "Single sign on URL". Entra calls it "Reply URL". Auth0 calls it "Application Callback URL".
- Entity ID / Audience
-
https://hjarni.com/auth/saml/<team_id>/metadata
Okta calls this "Audience URI (SP Entity ID)". Entra calls it "Identifier (Entity ID)". Auth0 has an
audiencekey in the SAML2 addon JSON. - Name ID format
- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
- Signature / digest algorithm
-
RSA-SHA256 / SHA256
Recommended. Hjarni requires the response or assertion to be signed but doesn't enforce a specific algorithm; SHA-256 is the sensible modern default.
- SP metadata XML
- https://hjarni.com/auth/saml/<team_id>/metadata
The SP metadata XML URL only works once the IdP values are saved in Hjarni (see Configure Hjarni), so for a first setup, type the fields above by hand. After that, an IdP that supports SP metadata import can read it from that URL.
Attribute statements
Hjarni reads the user's email from the SAML assertion. Any of these attribute names work out of the box:
email: common in Okta, Auth0, OneLogin.http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress: Microsoft Entra, ADFS, Auth0 (default mapping).urn:oid:0.9.2342.19200300.100.1.3: LDAP / OID style.
No extra attribute mapping is required for the major providers. Names are not imported: a first or last name in the assertion is ignored.
Configure Hjarni
From your IdP's setup page, copy three values:
- IdP SSO URL. Where Hjarni sends users to authenticate.
- IdP Entity ID / Issuer. Identifies the signing source.
- X.509 Certificate (PEM). Verifies the signed assertion.
Where to find each, by provider:
| Provider | Where to look |
|---|---|
| Okta | App > Sign On tab > SAML Setup > View SAML setup instructions. Copy "Identity Provider Single Sign-On URL", "Identity Provider Issuer", and the X.509 Certificate. |
| Microsoft Entra | Enterprise app > Single sign-on > section 3 (SAML Certificates) for the cert, section 4 (Set up <app name>) for "Login URL" (SSO URL) and "Microsoft Entra Identifier" (Issuer). |
| Auth0 | Application > Addons > SAML2 Web App > Usage tab. Copy "Identity Provider Login URL", "Issuer", and click Download on the certificate. |
| OneLogin | App > SSO tab. Copy "SAML 2.0 Endpoint (HTTP)", "Issuer URL", and download "X.509 Certificate". |
In Hjarni, go to your team > SSO (or visit /teams/<team_id>/sso) and paste the three values. Two more fields:
- Email domain. Needed to sign in from Hjarni: members type their work email at
/ssoand Hjarni finds your team by this domain. It also double-checks that the asserted email matches this domain. Without it, the test below fails, and with Require SSO on, members have no way to sign in. - Require SSO. See Enforce SSO below. Leave off for the first test.
Save. The Service Provider details below the form show the URLs to hand to your IdP admin if you haven't already, and once saved, a link to the SP metadata XML.
Test login
- Make sure your test user exists in your IdP and has been assigned to the Hjarni application.
- Open an incognito window (so you start with no Hjarni session).
- Visit
https://hjarni.com/sso, enter the user's work email, click Continue. - Your IdP's login screen appears. Authenticate.
- You should land on the Hjarni dashboard as that user, automatically added to the team.
If you assign a new user in the IdP after the team is set up, the next login will just-in-time provision them. No manual invite needed.
Enforce SSO
Once SSO is working for at least one team owner, you can require it for all team members. With Require SSO on:
- Password, Google, GitHub, and Apple logins are blocked for anyone on the team. They get redirected to
/ssowith a "your team requires SSO" message. - Signing in is only possible through your IdP. Remove a user there and they can't start a new sign-in, but a browser session or assistant they already connected keeps working until it expires or is revoked. Send
active: falsevia SCIM, or remove them from the team in Hjarni, to end their team access at once. Their own Hjarni account remains. - Team membership itself is still managed in Hjarni: owners can invite and remove members as usual. Enforcement gates how people sign in, not who is on the team.
Turn this on only after a successful SSO test as the team owner. If the IdP is misconfigured, enforcement can lock everyone out of the team. Including you.
SCIM provisioning (optional)
SCIM lets your IdP push user lifecycle changes to Hjarni without anyone needing to log in first. New hires get a seat the day they're added in Okta. Offboarded employees lose access to the team the moment they're removed.
Mint a bearer token
In Hjarni, go to your team > SCIM (or /teams/<team_id>/scim_tokens) and click Generate token. The token is shown once. Copy it immediately.
Hand it to your IdP
- SCIM base URL
- https://hjarni.com/scim/v2
- Auth method
- HTTP Header.
Authorization: Bearer <token> - Unique identifier field
- userName
- Supported actions
- Create user, update user, deactivate user
What's supported
- Users: full lifecycle. POST creates, PATCH updates,
active: falseor DELETE removes the team membership. The underlying account survives in case the user is in other teams. - Filters:
userName eq,externalId eq,emails eq. - Groups: returned as an empty list. We don't sync groups to team roles in v1. Set roles in Hjarni. A team has one owner; to hand it over, use Make owner on the team's Members page.
Test it without an IdP
curl -X POST https://hjarni.com/scim/v2/Users \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "alice@bigco.com",
"externalId": "okta-12345",
"active": true
}'
Troubleshooting
"Callback URL mismatch" on the IdP error page
Your IdP doesn't recognize the URL Hjarni is sending. The fix is in your IdP: open the SAML application's settings and confirm the Application Callback URL field contains exactly:
https://hjarni.com/auth/saml/<team_id>/callback
Watch for typos in the protocol (must be https://), the team_id, and trailing slashes.
"Audience mismatch" or "Invalid audience"
Your IdP's audience setting must match the SP entity ID exactly:
https://hjarni.com/auth/saml/<team_id>/metadata
Not the team's homepage, not the SSO URL, not with a trailing slash. The metadata URL.
"We couldn't find SSO for that email domain"
The email_domain field on the Hjarni SSO page doesn't match the domain of the email you entered. The fix is on the team side: the owner corrects email_domain in the team's SSO settings, and discovery finds the team again. Clearing it does not help, since discovery finds a team only by this field. There is no way around discovery: typing /auth/saml/<team_id> into the address bar won't work, since sign-in starts with a POST. Stuck? Email support.
"Sign in with SSO failed"
Hjarni rejected the IdP's response and recorded the exact reason internally. Possible values:
missing_config. SSO isn't configured for the team yet: the IdP SSO URL, issuer, and certificate haven't been saved on the team's SSO page.missing_email. The IdP didn't send the email under any of the supported claim names, or sent no NameID. Add an attribute statement that maps the user's email to one of the names listed under "Attribute statements" above.email_domain_mismatch. The asserted email's domain doesn't match the team's configuredemail_domain. Correct the field. Removing it skips this check but also turns off/ssodiscovery.email_taken. The asserted email already belongs to a Hjarni account that isn't on the team. Silently linking it would be an account-takeover vector, so the login is refused. Invite that account to the team first; once it's a member, SSO login binds to it.name_id_conflict. The asserted NameID doesn't match the one originally bound to that team membership. Treated as a potential takeover and rejected. Email support if a legitimate IdP migration triggered this.
Apart from missing_config, which shows "SSO is not configured for this team", rejection reasons aren't shown in the UI. Email support with the affected user's email address and we'll look up the reason for you.
SCIM "Test API Credentials" failing in Okta / Entra
The connection test probes /ServiceProviderConfig, /Schemas, /ResourceTypes, and a /Users list. If any of the four fail:
- Check the bearer token in your IdP is the exact plaintext you copied at generation time. If you lost it, revoke and regenerate at
/teams/<team_id>/scim_tokens. - Confirm the SCIM base URL is
https://hjarni.com/scim/v2. No trailing slash, no/Userssuffix. - Confirm the IdP is set to send the token in the HTTP
Authorizationheader asBearer <token>(not basic auth, not in the URL).
Related docs
Questions about SSO?
Email evert@hjarni.com
Give your AI a memory. Free.
Connect Claude or ChatGPT to notes they can actually read and write.
Give your AI a memory. Free.