4.2 SAML 2.0 SSO Integration
4.2.1 Overview
CBOM Secure uses Keycloak as its identity provider, and Keycloak brokers to the corporate SAML provider. The platform is therefore not itself the SAML service provider — Keycloak is. This is the single most important thing to state at the top of this page, because an administrator who assumes otherwise will look for SAML settings in the wrong place and will register the wrong entity ID with their identity provider.
The resulting flow is: user reaches the platform, is redirected to Keycloak, Keycloak redirects to the corporate provider, the user authenticates there, the assertion returns to Keycloak, Keycloak issues a platform session, and the user lands in the portal with roles derived from the assertion.
4.2.2 Prerequisites
-
On the platform: administrator access, and the external FQDN finalised. The FQDN appears in the service provider metadata, so changing it later requires reconfiguring the identity provider as well.
-
On the identity provider: permission to create and configure a SAML application, and permission to assign users and groups to it.
-
A decision on role mapping: which corporate group corresponds to which platform role. Make this decision before configuring, because it determines what claims the provider must send.
TLS working correctly on the external FQDN. SAML redirects will not work over an untrusted certificate.
4.2.3 Gather Service Provider Information
Sign in to the platform as an administrator.
Open the identity and authentication settings.
Retrieve the service provider metadata: the entity identifier, the assertion consumer service URL, the single logout URL where used, and the signing certificate.
Copy these exactly. A trailing slash difference in the assertion consumer service URL is a common and confusing failure — the assertion is issued and rejected, and the user sees a generic error.
4.2.4 Configure the Identity Provider
Create a new SAML application in the corporate identity provider.
Set the entity identifier and reply or assertion consumer service URL to the values gathered above.
Configure the name identifier — email address is the usual choice and should match what the platform will use to identify the user.
Configure a group or role claim. This is what drives platform authorisation, and the claim name must match what the platform expects.
Configure user attribute claims — at minimum email, given name and surname, so that user records are populated rather than appearing as bare identifiers.
Enable assertion signing. Note whether the provider signs the assertion, the response, or both, and record it — the platform must be configured to match.
Retrieve the identity provider metadata URL or metadata document, and its signing certificate.
Assign the users and groups who should have platform access. A user not assigned to the application will authenticate successfully at the provider and be refused by the platform, which reads as a platform fault.
4.2.5 Configure CBOM Secure to Trust the Identity Provider
Return to the platform authentication settings.
Supply the identity provider metadata URL, or upload the metadata document.
Confirm the signing certificate is imported and that signature validation is enabled. Do not disable signature validation to get past an error — an unvalidated assertion is an unauthenticated login.
Configure the claim-to-role mapping decided in 4.2.2.
Save the configuration. This can also be done through the API where configuration is managed as code.
4.2.6 Attribute and Role Mapping
-
The platform ships four roles: administrator, manager, user and auditor. Map each to a corporate group.
Decide what happens to a user who authenticates with no matching group. The safe default is to refuse access rather than grant a default role.
Role changes take effect on the live session, so a group change at the provider is reflected at the next login, and an administrator-side role change takes effect immediately.
User attributes are refreshed from the assertion on login, so a name or email change at the provider propagates without administrative action.
4.2.7 Test
Test in a private browser session with an account that has no existing platform session.
Confirm the redirect chain completes and the portal loads.
Confirm the user record shows the correct email and name.
Confirm the role is correct by checking that the navigation matches the expected role.
Test one account per mapped role, and one account with no mapping, to confirm the no-match behaviour.
Test single logout if configured.
Confirm the break-glass local account still works.
4.2.8 Troubleshooting
-
Claim not found: the group or role claim name at the provider does not match what the platform expects. Compare the actual assertion against the configured claim name; do not assume the provider is sending what its interface implies.
-
Invalid role mapping: the claim arrived but its value matches no configured mapping. Check for case sensitivity and for fully-qualified group names where a short name was configured.
-
Signature validation failed: a certificate mismatch, usually because the provider rotated its signing certificate. Re-import the metadata.
Access denied after a successful provider login — the user authenticated but is not assigned to the application, or has no mapped group.
-
Metadata URL not accessible: the platform cannot reach the provider metadata endpoint. This is a network or proxy problem, not a SAML problem.
-
User profile not updated: attribute claims are absent or misnamed. The login succeeds, so this is easily missed until a user list is reviewed.
-
Redirect returns to the login page: almost always an FQDN mismatch between the platform configuration, the certificate and the registered reply URL.