HOW TO IMPLEMENT SAML ?

Equipe Learning Updated 2026-05-22 13:32:29 UTC

As a first step, you should discuss the subject with your main contact to validate the implementation.

Data needed for the configuration

The client must be asked for the address where the metadata of its IdP is hosted. The SAML metadata contains, among others

the certificate whose associated private key will be used to sign the identity server responses
the URL that will allow the SSO to send an authentication request to this identity server

Normally the client will have to provide either a URL or a ready-made XML that will have to be examined and used to fill in the delegate configuration.

Generation of the certificate of our SP

We have a certification chain that allows us to create certificates, and for each new delegated authentication, we have to create a new certificate.
The procedure is out of the scope of this document.

SSO configuration to integrate this new IdP

Today the configuration is basic, and is done via a JSON field that is stored in the LDAP.

This file contains all the configuration of a SAML2 connector. Take it as an example for another one.

Notice the values:

  • onelogin.saml2.idp.entityid : the URL where the IdP exposes its metadata.
    It is mandatory, even if this metadata is inaccessible to the public. The SSO will try to connect to this URL to fetch the metadata, unless the configuration includes "braincube.metadata.fetch": "false" (for cases where the metadata is provided by email)

  • onelogin.saml2.idp.single_sign_on_service.url : this is the URL to which a user will be redirected when he wants to identify himself to us via this authentication delegate. Ideally, if the metadata is available through the IdP URL, this line can be left empty and will be filled in automatically by the SSO when it retrieves the metadata. Otherwise you have to examine the XML sent by the client and put the URL whose 'Binding' is urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect .

  • onelogin.saml2.sp.privatekey and onelogin.saml2.sp.x509cert : these two values contain the locations (in file:// format) where we will find the private key and the certificate that the SSO will use to sign its authorization requests. It is also this certificate that will be presented in the metadata exposed by the SSO.

  • braincube.email.domains.whitelist : a list of domains separated by a semicolon (; ). These domains restrict the users who can connect through this delegate to those whose email ends with this domain(s). This is a security measure to prevent a malicious IdP from authenticating users whose email ends in braincube.com for example.

  • braincube.certchain.file : If the IdP presents a certificate signed by a certification authority, it is important that the SSO can check the validity of the certification chain. For example, a manufacturer can provides its certification chain and signs its assertions with a certificate itself signed by other certificates (the "chain"). In this field we put the name of the file containing this chain, which will allow us to validate the whole chain of signature of the assertions.

Definition of access rights by group

We can define for a user a correspondence between the SAML group or groups and particular rights in the LDAP. This allows the SSO to "grantee" a user connected by delegated authentication on products with an access right level corresponding to his SAML group.
To do this, we can add the following elements to the JSON configuration:

  "braincube.groups.mapping": {
        "OEMAdminUser": [
            { "productId": "product1", "accessType": "ADMIN"},
            { "productId": "product2", "accessType": "USER"}
        ],
        "OEMUser": [
            { "productId": "product3", "accessType": "ADMIN"},
            { "productId": "product4", "accessType": "USER"}
        ]

This configuration is defined by the fields :

  • braincube.saml.attribute.group: name of the attribute of the SAML flow in which the group name is found. There can be several attributes with this name, if this is the case then all groups will be taken into account.
  • braincube.groups.mapping: Defines a json object containing the mappings.
  • OEMAdminUser or OEMUser: Name of the groups in the SAML.
  • productId: Defines the productId on which to add a "grant".
  • accessType : defines the type of access to put on this "grant".

Here in the example: If a user has the role named "OEMAdminUser", then he will have access to "product1" as admin and to "product2" as user.

Creation

To create this authentication delegate, you have to use the SSO Admin platform.While inside, go to Delegates part and you will be able to create new one here by choosing SAML protocol and by editing the JSON configuration field with data you prepared.
While the configuration is filled just save and launch the deployment with Deploy button.

Check in the logs that the delegate is loaded and, if necessary, that the metadata are retrieved from the IdP server.

Reverse Proxy modifications

To facilitate the use of login via delegation, we generate virtual URLs on our reverse proxy.
We need to add several things in the appropriate Braincube ansible configuration. To do this, prepare the following values:

  • delegateName: the name of the authentication delegate you created
  • ipSso : the internal ip of the SSO
  • urlSso: the URL of the sso, normally mybraincube.com, but could be pilot.blu-e.fr for a delegated authentication for one of our white label customers
  • vendor: ipleanware in most cases, but for white label customers, you have to put the vendor name

Then, this configuration will be deployed on Reverse proxy side.

location /saml {
    # We add the name of the delegate in the arguments in the requests. 
    # This syntax preserves the previous arguments if any
    set $args $args&delegate=${delegateName};
    proxy_pass http://${ipSso}:8080/sso-server/vendors/${vendor}/saml/saml.jsp;
    proxy_read_timeout 60s;

    proxy_set_header Host ${urlSso};
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# necessary to display the assets of the /saml page just above (like css or images)
location /sso-server {
    proxy_pass http://${ipSso}:8080$request_uri;
    proxy_read_timeout 60s;

    proxy_set_header Host ${urlSso};
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# redirection to metadata
location /metadata {
    return 301 https://${urlSso}/sso-server/ws/saml2/metadata/${delegateName};
}

From here, after RP reloading configuration, you should be able to let the first users log in.

Was this article helpful?

Powered by Zendesk