SAML SSO — Integration Guide

SAML (Security Assertion Markup Language) is an open standard for exchanging authentication data between an Identity Provider (IdP) and a Service Provider (SP). In this project, the OneIoT application acts as the SP, while an external IdP (Keycloak, Azure AD, Okta, ADFS, etc.) performs user authentication.

The application supports two separate SAML client registrations, each with its own Identity Provider connection and signing certificate:

Each portal has its own ACS URL, Entity ID, IdP entity ID, IdP SSO URL, IdP signing certificate, and post-authentication redirect URL. The two portals may point to the same IdP or to two completely independent IdPs.

To enable SAML SSO:

Relying party registrations are built programmatically at startup by SamlRelyingPartyConfig, using values from the app.saml.* properties in application.yaml. Spring Boot’s built-in Saml2RelyingPartyAutoConfiguration is explicitly excluded, so the spring.security.saml2.relyingparty.registration YAML section is not used by this project.

The Spring Boot auto-configuration is disabled in application.yaml:

The two registrations are driven by the following property block:

At startup, SamlRelyingPartyConfig.relyingPartyRegistrationRepository():

Key points:

Specific values:

The frontend receives the JWT token and sessionHash as query parameters:

The application automatically publishes SP metadata at:

Examples:

Each certificate is used for:

If both portals are served by the same IdP (same realm / same signing key), the same certificate content is used for both files — but the application still loads them as two separate files, one per registration.

Each file must be in X.509 PEM format with the following structure:

For Keycloak, the IdP certificate can be obtained from:

See Exporting IdP Signing Certificate for detailed step-by-step instructions. Repeat the export for each IdP/realm used by the SC and MC portals, saving the results as sc-idp.crt and mc-idp.crt respectively.

Returns the URL for redirecting the user to the IdP.

Authentication: not required (public endpoint).

Auxiliary endpoint returning the current authentication type.

Response when SAML is configured:

The frontend uses this endpoint to determine whether to show the login/password form or the SSO button.

The SC and MC portals use two separate realms — one per portal. Each realm hosts a single SAML client, so the two portals have fully independent users, signing keys, and attribute mappers.

Each realm contains one SAML client. The client for the Support Center lives in the oneiot-sc realm; the client for the Management Console lives in the oneiot-mc realm.

In each realm, for its respective client (oneiot-sp-sc in oneiot-sc, oneiot-sp-mc in oneiot-mc):

Each realm has its own signing key, so the export must be performed once per realm: from oneiot-sc for the Support Center, and from oneiot-mc for the Management Console. The result is two certificate files (sc-idp.crt and mc-idp.crt) in the application’s conf/ directory.

Repeat the following steps for each realm:

The file must be in X.509 PEM format with the following structure:

Repeat this step in both realms (oneiot-sc and oneiot-mc) so that users in either realm can carry the required custom attributes.

The username and email attributes already exist by default. You need to create the following additional attributes:

For each attribute:

Create users in the realm that matches the portal they are supposed to log into: Support Center users go into oneiot-sc, Management Console users go into oneiot-mc. The same person needing access to both portals must exist as a user in both realms.

To pass custom attributes in the SAML assertion, you need to create the same set of mappings in each realm’s client dedicated scope. Each client lives in its own realm, so the mappers must be added twice — once in oneiot-sc > oneiot-sp-sc, and once in oneiot-mc > oneiot-sp-mc.

After successful authentication, the IdP returns a SAMLResponse containing a SAML assertion with user attributes. The SamlAuthService.authenticateFromSamlPrincipal() method extracts these attributes and maps them to internal application fields.

SamlAuthService.extractClientType() determines the portal type using a three-level priority strategy:

After all attributes are extracted, UserService.createOrGetExternalUser(userRequest, clientType, zoneId) is called:

The SecurityConfig class defines two SecurityFilterChain beans:

The SAML filter chain intercepts requests matching:

Activated via @ConditionalOnProperty(name = "app.saml.enabled", havingValue = "true").

Sequence of actions on successful SAML authentication:

The main SAML authentication service. The authenticateFromSamlPrincipal() method performs:

During SAML authentication, SecurityConfig returns a no-op AuthenticationManager that throws ProviderNotFoundException. This is necessary to avoid StackOverflowError when AOP-proxying an empty ProviderManager.

SAML IdP certificates must be available to the backend container at ${app.home}/conf/ (i.e. /opt/app/conf/ inside the container). Place the files in the ui-backend/config/ directory on the host — this directory is mounted into /opt/app/conf by the backend container (see the volumes: section of compose.yml):

The SAML variables are not a separate file — they are part of the same database env file the backend already loads (.env.mysql or .env.oracle, in iot-web-app-build/docker/). That file ships with a SAML Configuration (Optional — disabled by default) block where SAML_ENABLED=false; to turn SAML on, set SAML_ENABLED=true and fill in the values in that same block. The relevant entries (example for a deployment where Keycloak runs on the same Docker host):

The ui-backend service already references this one file in compose.yml — a single unified env file, no SAML-specific one to attach:

Then start the stack with that same file:

After deployment, verify each item: