SAML Integration

1. Configure Enterprise and Role Binding

The first time a SAML SSO login is successful, the Abiquo API will need to create a user in the platform. This user requires an enterprise and a role, so do these steps to configure enterprise and role binding.

1. In Abiquo create enterprises with Names or enterprise propertyKeys 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

Matching examples

• abiquo.saml.attributes.enterprise.claims = example
  • the API will get the value of the attribute "example" 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 a property key called "example" that has a property value that matches the SAML Response value.
• abiquo.saml.attributes.enterprise.claims = organization,acc_id:account
  • the API will get the value of the attributes organization and acc_id. 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 by properties, and return the enterprise that has the property organization with the value from the SAML Response and the property account with the value from the SAML Response.

2. 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.

3. 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. 

4. Configure SameSite flag of login cookie

On the Abiquo Server, optionally set the abiquo.login.samesite property to control the value of the SameSite flag of the login cookie. See Abiquo Configuration Properties#samesite

5. Configure SAML Identity Provider

To enable Abiquo to identify and trust the SAML SSO Server (aka Identity Provider or 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

6. 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

7. Optionally generate the Service Provider metadata

If you do not have an 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 PHYS_DC_MANAGE 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"

8. 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.

9. Optionally 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.

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!",

10. Optionally configure a SAML enterprise pool

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

11. Optionally add multiple identity providers for SAML