SAML integration

Configure enterprise and role binding

The first time a user logs in with SAML SSO, the Abiquo API will create the user’s account in the platform. Before the user can log in, the administrator must create an Abiquo enterprise and role for the user and define their SAML attributes. Then the API can get the user’s SAML attributes, select the correct role, and assign it to the user. This is called enterprise and role binding.

Here are some examples of how Abiquo can match SAML attributes for enterprises:

• abiquo.saml.attributes.enterprise.claims = example

  • The API will get the value of the example attribute from the SAML Response. It will try to find an Abiquo enterprise with the same name. If it can't find an enterprise, it will look for an enterprise with an enterprise property key called example that has a property value that matches the SAML Response example attribute value.

• abiquo.saml.attributes.enterprise.claims = organization,acc_id:account

  • The API will get the value of the organization and acc_id attributes from the SAML Response. It will try to find an enterprise with a name that matches one of these values. If it can't find an enterprise, it will search the enterprise properties. It will return the enterprise that has the property organization with the value from the SAML Response and acc_id property with the value of account from the SAML Response.

To configure the enterprise and role binding do these steps:

1. In Abiquo create enterprises for your users and assign Names or enterprise property Keys that will match the values of SAML attributes.

2. On the Abiquo Server, set the abiquo.saml.attributes.enterprise.claims property to specify the SAML attributes to match. Abiquo will get the values of these attributes and search for an enterprise name or enterprise property with this key to match the SAML values.

3. In Abiquo create roles and set the External roles value to match the value of one or more SAML attributes. One Abiquo role can match multiple external roles, but each external role should only match one Abiquo role.

4. On the Abiquo Server, set the abiquo.saml.attributes.role.claim property to specify the SAML attribute to match the roles

Enable SAML authentication mode

Abiquo integrates different authentication options and the default authentication mode is abiquo, which is basic authentication for users stored in the Abiquo database.

To enable SAML in Abiquo:

1. On the Abiquo Server, set the abiquo.auth.module property to a value of saml.

2. Before you start the Abiquo API again, complete the configuration in the follow sections to ensure that Abiquo API will start successfully.

Configure login modules in the UI

To enable users to log in with SAML, set the following UI configuration properties in client-config-custom.json. See Configure Abiquo UI for more details. 

Configure SameSite flag of login cookie

Optionally, on the Abiquo Server set the abiquo.login.samesite property to control the value of the SameSite flag of the login cookie. See Abiquo configuration properties#samesite

Configure the maximum authentication age

On the Abiquo server set the abiquo.saml.authentication.maxage property to control the maximum time in seconds that users can use SAML single sign-on after their initial authentication with the IDP. The default value is 2073600 seconds, which is 24 days.

Configure SAML identity provider

To enable Abiquo to identify and trust the SAML SSO Server, which is the identity provider (IdP):

1. Get the IdP metadata and save it on the Abiquo Server

2. On the Abiquo Server, set the following property pointing to this file:
   abiquo.saml.metadata.identityprovider.path=/opt/abiquo/config/saml/identityprovider_metadata.xml

3. On the Abiquo Server, you must set the default IdP with the following property:
   abiquo.saml.metadata.identityprovider.default.id
   If you do not add this property, the Abiquo API will not start

Configure the Abiquo API as a SAML service provider

To configure Abiquo to act as a SAML service provider (SP) that can sign and encrypt SAML requests:

1. Create a dedicated keystore with the keys that Abiquo will need for signing and encrypting.

2. Configure the details of the keystore in Abiquo with the following properties:

   1. abiquo.saml.keys.keystore.path=/op/abiquo/config/saml/saml_keystore.jks

   2. abiquo.saml.keys.keystore.password=the_keystore_password

   3. abiquo.saml.keys.metadata.sign=true

   4. abiquo.saml.keys.signing.alias=alias_for_signing_key

   5. abiquo.saml.keys.signing.password=password_for_signing_key

   6. abiquo.saml.keys.encryption.alias=alias_for_encryption_key

   7. abiquo.saml.keys.encryption.password=password_for_encryption_key

3. To configure the type of binding that the API will offer for the IdP, set the following property:

   1. abiquo.saml.binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect

   We recommend that you use the same binding type as the IdP.

4. To configure the browser redirect to the Abiquo environment after a successful login, set the following property: 

   1. abiquo.saml.redirect.endpoint=https://<your-environment>/ui

Generate the service provider metadata

If you do not have a service provider (SP) metadata XML file, you can generate one using the Abiquo API.

1. Configure the SP properties as described in the above steps.

2. On the Abiquo Server, set the following properties with these values

   1. abiquo.saml.metadata.mode=generated

   2. abiquo.saml.metadata.serviceprovider.path= # can be left empty because it is not used

   3. abiquo.saml.mode=multi

3. Start the Abiquo API

4. Log in as an administrator user (with the Manage datacenter privilege) 

5. Perform an authenticated request to the path /api/saml/metadata

6. Save the metadata response in a file

After you obtain the SP metadata, do these steps:

1. Add the metadata XML file to the IdP

2. Provide the SP metadata to the Abiquo API as described below

We also recommend that you do these additional steps

1. Disable basic authentication. To do this, set the abiquo.saml.mode property to single (or just delete it because single is the default value).

2. Configure the API to use the provided metadata file and stop the API from generating metadata each time you restart it. To do this, set the abiquo.saml.metadata.mode property to provided

Provide the SP metadata to the service provider and the identity provider

The Abiquo API (SP) and the SAML IdP require the SP metadata XML file. To configure the SP metadata XML file for the Abiquo API:

1. Save the SP metadata XML file on the Abiquo Server

2. Add the following properties:

   1. abiquo.saml.metadata.serviceprovider.path=/opt/abiquo/config/saml/serviceprovider_metadata.xml

   2. abiquo.saml.metadata.mode=provided

Your environment is now ready to use SAML SSO, just start the API and open the user interface in the browser.

Configure custom login error messages for SAML

By default, when there is a login error, the UI displays a generic error view and the user can return to the main login screen.

Optionally, to display custom error messages, configure the redirect to add an error parameter.

On the Abiquo API Server, set the abiquo.saml.redirect.error.endpoint to point to your UI server and add an error code as follows:

abiquo.saml.redirect.error.endpoint = https://your.env.com/ui/?error=ERROR_CODE

Then for each error code, create a UI label with the error message text. For example, for US English, in lang_en_US_custom.json, you could create a label as follows:

  "login.error.SAMLERROR2": "Login failed!",

For details of more customizations, see Customize UI login errors.

Configure a SAML enterprise pool

Optionally, if you will only be using a single identity provider, you can enable users to log in to an enterprise pool of enterprises with the same enterprise claim value.

The login process will select the first matching enterprise from the pool.

To configure this option, set the following property.

abiquo.saml.login.allow.enterprise.pool = true

Add multiple identity providers for SAML

Table of Abiquo configuration properties for SAML