Single sign-on
HarborGuard supports two SSO protocols: SAML 2.0 and OpenID Connect (OIDC). Each SSO connection belongs to one organization. JIT provisioning creates a HarborGuard user the first time a verified IdP subject signs in; subsequent logins reuse the linked record.
HarborGuard does not support direct LDAP. To federate from a directory, point a SAML or OIDC IdP (Entra ID, Okta, JumpCloud, etc.) at your LDAP backend and connect HarborGuard to that IdP.
Service Provider URLs
Each SSO connection has a stable identifier connId returned when you create it under Settings -> Security -> SSO. The IdP-facing URLs follow a fixed pattern. Replace https://harborguard.co with your tenant URL if you are on a private deployment.
SAML
| Purpose | URL |
|---|---|
| SP metadata | https://harborguard.co/api/sso/saml/{connId}/metadata |
| Assertion Consumer Service (ACS) | https://harborguard.co/api/sso/saml/{connId}/acs |
| Initiate login (SP-initiated) | https://harborguard.co/api/sso/saml/{connId}/login |
| Audience / Entity ID | https://harborguard.co/api/sso/saml/{connId} |
| Name ID format | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| Binding | HTTP-POST |
The metadata document is publicly fetchable so you can paste its URL into the IdP and let it populate ACS, audience, and signing certs automatically.
OIDC
| Purpose | URL |
|---|---|
| Redirect URI | https://harborguard.co/api/sso/oidc/{connId}/callback |
| Initiate login | https://harborguard.co/api/sso/oidc/{connId}/login |
| Required scopes | openid email profile (add groups if you need group claims) |
| Response type | code (Authorization Code Flow with PKCE) |
Required claims
HarborGuard reads the following from the IdP. Map your directory attributes to these in the IdP UI.
| HarborGuard field | SAML attribute | OIDC claim |
|---|---|---|
| Email (required, unique) | email or NameID if email-format | email |
| Display name | displayName | name |
| Stable subject ID | NameID | sub |
| Group memberships (for role mapping) | groups (multi-value) | groups |
Email must be verified by the IdP. Unverified emails are rejected.
Okta — SAML walkthrough
Create the app integration
In the Okta admin console, go to Applications -> Create App Integration -> SAML 2.0.
Set the Single sign-on URL
Single sign-on URL: https://harborguard.co/api/sso/saml/{connId}/acs.
Set the Audience URI
Audience URI: https://harborguard.co/api/sso/saml/{connId}.
Set the Name ID format
Name ID format: EmailAddress.
Set the Application username
Application username: Email.
Configure attribute statements
email->user.emaildisplayName->user.firstName + " " + user.lastName
Add a group attribute for role mapping
Name groups, filter Matches regex .* (or restrict to the groups you want to push).
Capture the IdP metadata
Finish the wizard, then on the Sign On tab click View Setup Instructions and copy the IdP SSO URL, IdP Entity ID, and X.509 certificate.
Activate the connection in HarborGuard
In HarborGuard paste those three values into the SSO connection and click Activate.
Okta — OIDC walkthrough
Create the app integration
Go to Applications -> Create App Integration -> OIDC -> Web Application.
Set the sign-in redirect URI
Sign-in redirect URI: https://harborguard.co/api/sso/oidc/{connId}/callback.
Set the sign-out redirect URI
Sign-out redirect URI (optional): https://harborguard.co/login.
Choose grant types
Grant types: Authorization Code (PKCE recommended).
Assign access
Assignments: pick the groups that should be able to sign in.
Copy client credentials
Copy Client ID and Client Secret, plus the issuer (https://{your-okta-domain}.okta.com).
Create the connection in HarborGuard
In HarborGuard create an OIDC connection with those values and set Scopes to openid email profile groups.
Test and activate
Click Test to run a discovery probe and Activate when it succeeds.
Microsoft Entra ID — SAML walkthrough
Create the enterprise application
Go to Entra admin -> Enterprise applications -> New application -> Create your own, non-gallery.
Choose SAML
Single sign-on -> SAML.
Basic SAML configuration
- Identifier (Entity ID):
https://harborguard.co/api/sso/saml/{connId} - Reply URL (ACS):
https://harborguard.co/api/sso/saml/{connId}/acs
Configure Attributes & Claims
email->user.maildisplayName->user.displayname- Add a group claim, format sAMAccountName or Group ID depending on how you want to match in role mappings.
Provide IdP metadata to HarborGuard
Download the Federation Metadata XML and upload it in the HarborGuard SSO connection, or paste the Login URL, Entra Identifier, and certificate manually.
Microsoft Entra ID — OIDC walkthrough
Register the application
Go to Entra admin -> App registrations -> New registration.
Set the redirect URI
Redirect URI (Web): https://harborguard.co/api/sso/oidc/{connId}/callback.
Generate a client secret
After registration, Certificates & secrets -> New client secret, copy the value.
Configure API permissions and group claim
API permissions: add Microsoft Graph delegated openid, email, profile. To get groups in the ID token, configure Token configuration -> Add groups claim.
Configure HarborGuard
In HarborGuard, set:
- Issuer:
https://login.microsoftonline.com/{tenant-id}/v2.0 - Client ID and Client Secret from above
- Scopes:
openid email profile
Google Workspace — SAML walkthrough
Add a custom SAML app
Go to Admin console -> Apps -> Web and mobile apps -> Add custom SAML app.
Copy Google's IdP details
Copy Google's SSO URL, Entity ID, and Certificate for use in HarborGuard.
Configure Service Provider details
- ACS URL:
https://harborguard.co/api/sso/saml/{connId}/acs - Entity ID:
https://harborguard.co/api/sso/saml/{connId} - Name ID format: EMAIL
- Name ID: Basic Information -> Primary email
Configure attribute mapping
email-> Primary emaildisplayName-> First name + Last name
Enable access
Turn the app ON for everyone or for the specific OU that should have access.
Group-to-role mapping
After the connection is active, map IdP groups to HarborGuard roles in Settings -> Security -> Role mappings. Groups not matched fall back to the default role (Viewer unless changed).
See User provisioning for details on how mappings are evaluated and how team membership can be inferred from the same group claim.
Domain allowlisting
To require all sign-ins to come from approved email domains, configure Settings -> Security -> Allowed domains. Both password and SSO logins are rejected if the user's email domain is not on the list.
Testing and troubleshooting
The SSO connection page shows the timestamp and reason of the last failure. The most common causes:
| Reason code | Meaning |
|---|---|
weak_alg | The IdP signed the SAML response with SHA-1 or no signature. Switch to SHA-256. |
replayed | A SAML assertion was reused. Check IdP clock skew. |
protocol_mismatch | The connection is configured for SAML but the IdP sent OIDC, or vice versa. |
id_token_invalid | OIDC ID token missing sub or failed signature verification. |
decrypt_failed | The stored OIDC client secret could not be decrypted. Re-enter the secret. |
The audit log records sso.login.initiated, sso.login.success, and sso.login.failed for every attempt.