Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.


Abiquo 5.0

Skip to end of metadata
Go to start of metadata

Author: Sergi Castro

Abiquo provides an integration to log in the platform with SAML SSO using SAML 2.0. Please read ALL of this documentation before starting to configure your environment.


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.

  1. In Abiquo create enterprises with 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.
    1. For a configuration abiquo.saml.attributes.enterprise.claims = example, the API will get the value of the attribute example from the SAML Response and will use it to find the enterprise with a name matching this value; if not found, it will try to find an enterprise with a property with key example and the value extracted from the SAML Response.
    2. For a configuration abiquo.saml.attributes.enterprise.claims = organization,acc_id:account, the API will extract the value of the attributes organization and acc_id and first it will try to find an enterprise matching the name with one of these values; if not found, it will search by properties, returning the enterprise that matches the property organization with the value from the SAML Response and the property account with the value from the SAML Response.
  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, but you can only enable one mode at a time for user login. 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. 

Property

Description

client.auth.moduleAbiquo login modules to use with options for Basic Auth (default), Open ID, and SAML. See client-config-default.json for examples
client.skip.login.viewBy default, when in OpenID mode, Abiquo shows an initial screen with a link to the Authentication portal. If this property is set to true, then Abiquo will not display the initial screen and will redirect users directly to the Authentication portal.


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


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

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

The API SAML metadata path is always enabled but it returns "provided" or "generated" metadata, depending on the value of the metadata.mode property.

This path is protected, so the property abiquo.saml.mode=multi allows the API to enable basic authentication and SAML SSO authentication. This means that even if the SAML authentication is not already finished, you'll be able to perform the request with basic auth.


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

Table of Abiquo Configuration Properties for SAML

 

KeyDescriptionRequiredRole

abiquo.auth.module

Sets the authentication module to use in the Abiquo Platform.

Accepts: abiquo, saml, openid, ldap

Yes

ABIQUO ADMIN

abiquo.saml.mode

Indicates the SAML mode to use.

Accepts:

  • single: only SAML is allowed to authenticate users
  • multiple: SAML and Basic Auth are allowed to authenticate users.

No

Default: single

ABIQUO ADMIN

abiquo.saml.redirect.endpoint

URI redirect for a successful Abiquo login using SAML SSO.

Accepts: any valid URI

Example: https://your.env.com/ui

Yes

ABIQUO ADMIN

abiquo.saml.redirect.error.endpoint

URI redirect for an unsuccessful Abiquo login using SAML SSO.

Accepts: any valid URI

No

Default: /error.html

ABIQUO ADMIN

abiquo.saml.metadata.mode = provided


Indicates if the SP metadata is provided or must be generated by the API.

Accepts:

  • provided: use existing metadata defined with the following property: abiquo.saml.metadata.serviceprovider.path
  • generated: the API should generate the metadata. Requires the Abiquo Server to have an SP configuration

No

Default: generated

ABIQUO ADMIN

abiquo.saml.metadata.serviceprovider.path

Indicates the location of the SP metadata to load.

Accepts: Any location path of the file to read

Only if abiquo.saml.metadata.mode is set to provided

ABIQUO ADMIN

abiquo.saml.metadata.identityprovider.path

Indicates the location of the IDP metadata to load.

Accepts: Any location path of the file to read

Yes

ABIQUO ADMIN

abiquo.saml.metadata.generator.bindingSSO

If abiquo.saml.metadata.mode is set to generated, this property will indicate which binding must be allowed.

Accepts: A coma-separated value with the binding names

No

Default: POST, Artifact

ABIQUO ADMIN SAML ADMIN

abiquo.saml.keys.keystore.path

Indicates the location of the Java keystore from which to extract the keys to sign and/or encrypt the SAML requests.

Accepts: Any location path of the file to read

Yes

ABIQUO ADMIN

abiquo.saml.keys.keystore.passwordHave the password to unlock the Java keystore from location indicated by abiquo.saml.keys.keystore.path property.Yes

ABIQUO ADMIN

abiquo.saml.keys.signing.alias

The alias of the key to use for signing SAML Requests

Accepts: any string

Yes

ABIQUO ADMIN

abiquo.saml.keys.signing.password

The password of the keys to use for signing SAML Requests

Accepts: any string

Yes

ABIQUO ADMIN

abiquo.saml.keys.encryption.alias

The alias of the key to user for encryption of SAML Requests

Accepts: any string

Yes

ABIQUO ADMIN

abiquo.saml.keys.encryption.password

The password of the key to use for encryption of SAML RequestsYes

ABIQUO ADMIN

abiquo.saml.keys.metadata.sign

Indicates if the SAML Requests must be signed.

Accepts: a boolean

No

Default: false

ABIQUO ADMIN SAML ADMIN

abiquo.saml.binding

Indicates the binding profile to allow.

Accepts: the SAML binding profile's URN

Yes

SAML ADMIN

abiquo.saml.attributes.user.id.claim

Indicates which SAML Response attribute must identify the user as unique, if not set up, the principal will be used.

Accepts: any string

No

SAML ADMIN

abiquo.saml.attributes.role.claim

Indicates which SAML Response attribute must be read to find the role to assign the user during a successful login.

Accepts: any string

Yes

SAML ADMIN

abiquo.saml.attributes.enterprise.claims

Indicates which SAML Response attributes must be read to find the enterprise to assign to the user during a successful login.

Accepts: a comma-separated list of the claim attribute and the enterprise property key separated by a colon.

Pattern: <saml-attr1>:<ent-prop1>,<saml-attr2>:<ent-prop2>

Yes

SAML ADMIN

abiquo.saml.attributes.user.firstname.claim

Indicates which attribute must be read to find the user name.

Accepts: any string

No

Default: FirstName

SAML ADMIN

abiquo.saml.attributes.user.lastname.claim

Indicates which attribute must be read to find the user last name.

Accepts: any string

No

Default: LastName

SAML ADMIN

abiquo.saml.attributes.user.email.claim

Indicates which attribute must read in order to find the user email.

Accepts: any string

No

Default: EmailAddress

SAML ADMIN