Page Comparison

Table of Contents

Info
This document describes how to configure the SAML integration to log in the platform with SAML SSO using SAML 2.0. Please read all of this documentation before you start to configure your environment.

...

Log in to Abiquo as cloud admin
Go to Users
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
the
1. 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
Go to Roles
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

...

Log in to the Abiquo server as the system administrator
Create a folder to store the configuration
Code Block
mkdir /opt/abiquo/config/saml
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
Create a metadata file for the identity provider, for example, at /opt/abiquo/config/saml/idp_metadata.xml and edit this file.

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>

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

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"
      }
  ]

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

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

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)

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

...

Add multiple identity providers for SAML

...

Table of Abiquo configuration properties for SAML

...

Key

...

Description

...

Required

...

Role

...

Sets the authentication module to use in the Abiquo Platform.
Accepts: abiquo, saml, openid, ldap

...

Yes

...

Status

colour	Blue
title	admin

...

abiquo.login.samesite

...

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:

Save the metadata for the new IdPs, as for the first IdP
For the default IdP, edit the metadata and set the Default attribute
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
Share the Abiquo SP data with the new IdPs
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.

Note

When you enable this feature, Abiquo will change the XML security metadata of the Abiquo application. Abiquo will add the beans for new IdPs and mark the default IdP in the metadata configuration of security-saml-generated-beans.xml and security-saml-provided-beans.xml.

Before you upgrade Abiquo, you must back up the security beans configuration.
After you upgrade Abiquo, when there is a new version of the security beans files, you must add the default IdP and the IdP beans again

...

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

Key

Description

Required

Role

abiquo.auth.module

Sets the authentication module to use in the Abiquo Platform.
Accepts: abiquo, saml, openid, ldap

Yes

Status

colour	Blue
title	admin

abiquo.login.samesite

Control the value of the SameSite flag of the login cookie.
See Abiquo configuration properties#samesite

No
Default: strict

Status

colour	Blue
title	admin

abiquo.saml.authentication.maxage

New in Abiquo 6.0.0
Required to start SAML and Abiquo
Maximum time in seconds the system allows users to use SAML single sign-on after their initial authentication with the IDP.
Required to start SAML
Default: 2073600
Status
colour Blue
title 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
Status
colour Blue
title 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
Status
colour Blue
title admin
abiquo.saml.redirect.error.endpoint
URI redirect for an unsuccessful Abiquo login using SAML SSO. This has to be set to a query parameter, "?error", or a valid URI like the one from the example.
Accepts: any valid URI
Example: https://your.env.com/ui/?error=ERROR_CODE
See Configure UI login errors
No
Default:
?error
Status
colour Blue
title 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
Status
colour Blue
title 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
Status
colour Blue
title admin
abiquo.saml.metadata.identityprovider.path
Indicates the location of the IdP metadata to load.
Accepts: Any location path of the file to read. For multiple identity providers, use a comma separated list
Yes
Status
colour Blue
title 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 comma-separated list with the binding names
No
Default: POST, Artifact
Status
colour Blue
title admin

Status
colour Yellow
title 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
Status
colour Blue
title admin
abiquo.saml.keys.keystore.password
The password to unlock the Java keystore from location indicated by abiquo.saml.keys.keystore.path property.
Yes
Status
colour Blue
title admin
abiquo.saml.keys.signing.alias
The alias of the key to use for signing SAML Requests
Accepts: any string
Yes
Status
colour Blue
title admin
abiquo.saml.keys.signing.password
The password of the key to use for signing SAML Requests
Accepts: any string
Yes
Status
colour Blue
title admin
abiquo.saml.keys.encryption.alias
The alias of the key to use for encryption of SAML Requests
Accepts: any string
Yes
Status
colour Blue
title admin
abiquo.saml.keys.encryption.password
The password of the key to use for encryption of SAML Requests
Yes
Status
colour Blue
title admin
abiquo.saml.keys.metadata.sign
Indicates if the SAML Requests must be signed.
Accepts: a boolean
No
Default: false
Status
colour Blue
title admin

Status
colour Yellow
title saml admin
abiquo.saml.binding
Indicates the binding profile to allow.
Accepts: the SAML binding profile's URN
Yes
Status
colour Yellow
title saml admin
abiquo.saml.attributes.user.id.claim
Indicates which SAML Response attribute must identify a unique user; if not set up, the principal will be used.
Accepts: any string
No
Status
colour Yellow
title saml admin
abiquo.saml.attributes.role.claim
Indicates which SAML Response attribute must be read to find the role to assign to the user during a successful login.
Accepts: any string
Yes
Status
colour Yellow
title 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. Matches an enterprise name or an enterprise property key.
Accepts: a comma-separated list of the claim attributes, with an optional enterprise property key separated by a colon.
Pattern: <saml-attr1>:<ent-prop1>,<saml-attr2>:<ent-prop2>
Yes
Status
colour Yellow
title 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
Status
colour Yellow
title saml admin
abiquo.saml.attributes.user.
lastname
firstname.claim
Indicates which attribute must be read to find the user
last
name.
Accepts: any string
No
Default:
LastName
FirstName
Status
colour Yellow
title saml admin
abiquo.saml.attributes.user.
email
lastname.claim
Indicates
which attribute must be read in order to find the user email.
Accepts: any string
No
Default: EmailAddress
Status
colour Yellow
title saml admin
abiquo.saml.login.allow.enterprise.pool
Allow the use of multiple enterprises with the same enterprise claim property as a pool. Will assign the user to the first enterprise match. Only valid for SAML mode, not for SAML + user (multiple IDPs).
Accepts: boolean
which attribute must be read to find the user last name.
Accepts: any string
No
Default:
false
LastName
Status
colour Yellow
title saml admin
abiquo.saml.
metadata
attributes.
identityprovider
user.
default
email.
id
Sets the default SAML IdP
Accepts: The entityID attribute of the default IdP from its metadata
Yes
claim
Indicates which attribute must be read in order to find the user email.
Accepts: any string
No
Default: EmailAddress
Status
colour
Blue
Yellow
title
abiquo
saml admin
abiquo.saml.
metadata
login.
identityprovider
allow.
userdomain
enterprise.
map
For multiple IdPs, map the user domains to the IdPs
Accepts: Comma separated list of email address domains and IdPs
Yes, for multiple IdPs
pool
Allow the use of multiple enterprises with the same enterprise claim property as a pool. Will assign the user to the first enterprise match. Only valid for SAML mode, not for SAML + user (multiple IDPs).
Accepts: boolean
No
Default: false
Status
colour
Blue
Yellow
title
abiquo admin

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.

...

Property

...

Description

...

client.login.modules

...

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

You can copy the options from client-config-default.json

...

client.skip.login.view

...

By default, when in OpenID or SAML mode, Abiquo displays 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.

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

...

saml admin

abiquo.saml.metadata.identityprovider.default.id

Sets the default SAML IdP
Accepts: The entityID attribute of the default IdP from its metadata

Yes

Status

colour	Blue
title	abiquo admin

abiquo.saml.metadata.identityprovider.userdomain.map

For multiple IdPs, map the user domains to the IdPs
Accepts: Comma separated list of email address domains and IdPs

Yes, for multiple IdPs

Status

colour	Blue
title	abiquo admin

...

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.

Property

Description

client.login.modules

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

You can copy the options from client-config-default.json

client.skip.login.view

By default, when in OpenID or SAML mode, Abiquo displays 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.

Versions Compared

Old Version 24

New Version Current

Key

Add multiple identity providers for SAML

Table of Abiquo configuration properties for SAML

About enterprise and role binding

Table of Abiquo configuration properties for SAML

Table of UI properties for SAML

About enterprise and role binding

Table of UI properties for SAML