Page Comparison

...

...

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.

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

...

Property

...

Description

...

client.auth.module

...

Configure Abiquo modules to log in with Basic Auth (default), Open ID, SAML, or SAML + user.
For the initial SAML configuration, use SAML. When you add multiple IdPs, use SAML + user.
See client-config-default.json for details.

...

client.skip.login.view

...

By default, when in OpenID or SAML 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 SameSite flag of login cookie

...

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 (aka Identity Provider or IdP):

...

Get the IdP metadata and save it on the Abiquo Server

...

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

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:

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:

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.

...

Configure your SAML identity provider

We assume that you are already using SAML and that you already have your own IdP configuration.

To configure Azure Active Directory as an IdP for Abiquo testing:

1. Go to Azure portal (https://portal.azure.com)

2. Create an Azure Active Directory

   1. For the Organization use Default Directory

   2. For the Domain use MY_ORG.onmicrosoft.com and replace MY_ORG with your organization name

3. Switch to the directory and create an Application

   1. Go to Enterprise applications

   2. Click Create your own application

   3. Select the Integrate any other application you don't find in the gallery (Non-gallery) option

   4. For the Name enter samlidp and click Create. Then wait for it to complete.

4. Go to Single sign-on, for the Authentication method, select SAML, and set the following values.

   1. Basic SAML Configuration: add Abiquo URLs to authorize it as a client that can use this SAML IDP.

      1. Identifier (Entity ID): https://ABIQUO_FQDN:443/api/saml/metadata
         Replace ABIQUO_FQDN with the domain name of your Abiquo server

      2. Reply URL (Assertion Consumer Service or ACS URL): https://ABIQUO_FQDN:443/api/saml/SSO
         Replace ABIQUO_FQDN with the domain name of your Abiquo server

      3. Sign on URL: Set an empty value

   2. SAML Claims: create and set the claims you want to retrieve from AAD users in Abiquo.
      For example:

      1. abq-enterprise: user.department

      2. abq-role: user.jobtitle

      3. user.userprincipalname

      4. user.givenname

      5. user.surname

      6. user.mail

   3. Go to the AAD organization main page and create SAML users.

      1. Name: This will set the username in Abiquo

      2. First Name

      3. Last Name

      4. Job title: This will set the user role in Abiquo, e.g., CLOUD_ADMIN_EXTERNAL

      5. Department: This will set the enterprise in Abiquo, e.g., Abiquo

   4. Add the users to the SAML IDP application we created before in order to authorize it to log in with SAML.

...

Create enterprises and roles for SAML

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.

1. Log in to Abiquo as cloud admin

2. Go to Users

3. Create enterprises with Names or Properties to match the value of a SAML attribute. From our example above, we will match the SAML Department attribute

   1. Enterprise Name: Abiquo

   2. OR if your enterprise names do not match SAML attributes, create or edit an enterprise, go to Properties and create a property to match.

      1. Edit an enterprise (for example, Name = My favorite enterprise)

      2. Create an Enterprise property

         1. Key: department

         2. Value: Abiquo

4. Go to Roles

5. Create roles with External roles to match the value of a SAML attribute. From our example above, we will match Job title:

   1. Role Name: CLOUD_ADMIN_EXTERNAL

   2. External roles: CLOUD_ADMIN_EXTERNAL

...

Configure SAML on Abiquo server

To configure SAML on the Abiquo server:

1. Log in to the Abiquo server as the system administrator

2. Create a folder to store the configuration

   Code Block
   mkdir /opt/abiquo/config/saml

3. Download the federation metadata XML file for your configuration. This may be from a link like:
   https://login.microsoftonline.com/<TenantDomainName>/FederationMetadata/2007-06/FederationMetadata.xml
   See https://learn.microsoft.com/en-us/azure/active-directory/azuread-dev/azure-ad-federation-metadata#federation-metadata-endpoints

4. Create a metadata file for the identity provider, for example, at /opt/abiquo/config/saml/idp_metadata.xml and edit this file.

5. Open the metadata XML file, and copy the EntityDescriptor bracket with only the IDPSSODescriptor bracket inside it. Paste it in your metadata file for the entity provider.
   It should look something like this but with different values for your identity provider.

   Code Block
   <?xml version="1.0" encoding="utf-8"?> <EntityDescriptor ID="_d75abe92_blah" entityID="https://sts.windows.net/d123456-blah/" xmlns="urn:oasis:names:tc:SAML:2.0:metadata"> <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> ... </IDPSSODescriptor> </EntityDescriptor>

   1. The entityID should be the value from your file. It may be something like this: https://sts.windows.net/d12345678-123e-49321-1234-1234abcd567890/

   2. The EntityDescriptor ID should also be the value from your file.

6. Edit /var/www/html/ui/config/client-config-custom.json and add the following configuration to allow SAML login.

   Code Block
   "client.login.modules": [ { "label": "Basic Auth", "description": "Basic Auth login", "templateUrl": "modules/login/authenticationmodules/basicauthentication/partials/basicauthenticationloginview.html", "cookieName": "" }, { "label": "SAML", "description": "SAML login", "templateUrl": "modules/login/authenticationmodules/saml/partials/samlloginview.html", "cookieName": "ABQSAMLTOKENS" } ]

7. Edit /opt/abiquo/config/abiquo.properties and configure the following properties.
   

   Code Block

   abiquo.auth.module = saml abiquo.saml.mode = multi abiquo.login.samesite = strict # Mandatory 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 represents 24 days. abiquo.saml.authentication.maxage = 2073600 abiquo.saml.redirect.endpoint = https://ABIQUO_FQDN/ui abiquo.saml.redirect.error.endpoint = https://ABQIUO_FQDN/ui/?error abiquo.saml.keys.keystore.path = /opt/abiquo/config/saml/MY_SAML_KEYSTORE abiquo.saml.keys.keystore.password = MY_SAML_KEYSTORE_PASSWORD abiquo.saml.keys.signing.alias = MY_SAML_APP_NAME abiquo.saml.keys.signing.password = MY_SAML_KEY_PASSWORD abiquo.saml.keys.encryption.alias = MY_SAML_APP abiquo.saml.keys.encryption.password = MY_SAML_KEY_PASSWORD abiquo.saml.keys.metadata.sign = false abiquo.saml.binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect abiquo.saml.metadata.mode = generated #abiquo.saml.metadata.serviceprovider.path = /opt/abiquo/config/saml/sp_metadata.xml abiquo.saml.metadata.identityprovider.default.id = MY_ENTITY_ID # For >1 IDPs, add commas between XML paths abiquo.saml.metadata.identityprovider.path = /opt/abiquo/config/saml/idp_metadata.xml # For >1 IDPs, add commas between pairs of values abiquo.saml.metadata.identityprovider.userdomain.map = myorg.onmicrosoft.com=MY_ENTITY_ID # Set the claim names we have set up before in Azure AD abiquo.saml.attributes.role.claim = abq-role abiquo.saml.attributes.enterprise.claims = abq-enterprise abiquo.saml.attributes.user.id.claim = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name abiquo.saml.attributes.user.firstname.claim = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname abiquo.saml.attributes.user.lastname.claim = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname abiquo.saml.attributes.user.email.claim = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

   1. The #abiquo.saml.metadata.serviceprovider.path property should be commented out because first you can generate the metadata and later provide it with the file saved at this path

   2. Replace the following values with the values for your environment:

      1. ABIQUO_FQDN

      2. MY_SAML_KEYSTORE

      3. MY_SAML_KEYSTORE_PASSWORD

      4. MY_SAML_APP_NAME

      5. MY_SAML_KEY_PASSWORD

      6. MY_SAML_APP

      7. MY_SAML_KEY_PASSWORD

      8. MY_ENTITY_ID: you can get this from the Azure federation XML. It may be something like https://sts.windows.net/d12345678-123e-49321-1234-1234abcd567890/ 

8. Create a keystore with the above keystore values.

   Code Block
   cd /opt/abiquo/config/saml keytool -genkey -v -keystore MY_SAML_KEYSTORE -storepass MY_SAML_KEYSTORE_PASSWORD -alias MY_SAML_APP_NAME -keypass MY_SAML_KEY_PASSWORD -keyalg RSA -keysize 2048 -validity 10000

   (In our test system we are used the one value for the signing and encryption password as MY_SAML_KEY_PASSWORD)

9. Restart the Abiquo API

10. Check that the API works and has started successfully by logging in to Abiquo with basic auth as admin

...

Configure Abiquo as the service provider

To configure Abiquo as a service provider, obtain the metadata, save it to a file, and then enable the use of provided data.

1. Log in the Abiquo API server as an administrator

2. Generate the SP metadata:

   Code Block
   curl -k -u ADMIN_USER:ADMIN_PASSWORD https://ABIQUO_FQDN:443/api/saml/metadata \ > /tmp/curl_sp_metadata.xml

   Replace ADMIN_USER, ADMIN_PASSWORD, and ABIQUO_FQDN with values for your environment

3. Save it to your SAML configuration folder

   Code Block
   xmllint --format /tmp/curl_sp_metadata.xml > /opt/abiquo/config/saml/sp_metadata.xml

4. Edit the abiquo.properties file and set the values as follows

   Code Block
   abiquo.saml.metadata.mode = provided abiquo.saml.metadata.serviceprovider.path = /opt/abiquo/config/saml/sp_metadata.xml

5. Restart the Abiquo API

6. Check that the API works and has started successfully by logging in with SAML

   1. Username: USER_NAME@MY_ORG.onmicrosoft.com

Additional configuration

We recommend that you do these additional steps

1. Add the metadata XML file to the IdP

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

...

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

You can configure more than one identity provider for SAML. With the configuration, when the user enters their email address to log in, Abiquo will select the IdP based on its domain name, or it will use the default IdP. 

Abiquo still uses the same IdP configuration for all providers, for example, it will search for the same abq-role attribute to match an Abiquo role.

To configure an existing SAML integration with more IdPs, do these steps on the Abiquo Server:

1. Save the metadata for the new IdPs, as for the first IdP

2. For the default IdP, edit the metadata and set the Default attribute

3. Edit the abiquo.properties file to make these changes:

   1. Add the paths to the metadata of the new IdPs as a comma separated list to the abiquo.saml.metadata.identityprovider.path property

   2. To set the default IdP, add the new abiquo.saml.metadata.identityprovider.default.id property

   3. To map the user email domains to IdPs, set the new abiquo.saml.metadata.identityprovider.userdomain.map property with a comma separated list of keys and values. For example:

      Code Block
      abiquo.saml.metadata.identityprovider.userdomain.map = example.com=https://sts.example.com/ffff2108-833e-4940-87e6-3d39ce9adb70/,abiquo.com=https://idp.example.com

      Do not use a comma , in a key or a value
      Do not use use an equals sign = in the key

4. Share the Abiquo SP data with the new IdPs

5. On the UI server, edit the client-config-custom.json file and change the client.login.module property from SAML to SAML + user.
   For more details, see the examples in client-config-default.json file.

For this feature, there is a new /saml/idp endpoint in the Abiquo API where the UI will send a GET request with the user domain. This endpoint will return a redirect to the usual /saml/login endpoint with the appropriate IdP. Then the login will continue as for a single IdP.

...

About enterprise and role binding

The Abiquo 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.

...

Table of Abiquo configuration properties for SAML

...

Table of UI properties for SAML

For SAML, you can configure the following UI configuration properties in client-config-custom.json. See Configure Abiquo UI for more details.