Versions Compared

Old Version 19

changes.mady.by.user MS

Saved on

compared with

New Version 20

changes.mady.by.user MS

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.

Table of Contents

...

start-numbering-ath2


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

...

  1. saml

...

  1. .

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

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 (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
    (warning)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

...

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

...

  1. the PHYS_DC_MANAGE privilege) 

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

  3. Save the metadata response in a file

Tip

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

...

  1. provided

...

  1. metadata file and stop the API from generating metadata each time you restart it. To do this, set the abiquo.saml.metadata.

...

  1. mode property to

...

  1. 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
Code Block
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:

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

...

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.

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

...

Add multiple identity providers for SAML

Include Page
Add multiple identity providers for SAML
Add multiple identity providers for SAML


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
colourBlue
title

abiquo

admin

(warning) abiquo.saml.authentication.maxage

New in Abiquo 6.0.0

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
colourBlue
title

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

Status
colourBlue
title

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

Status
colourBlue
title

abiquo

admin

abiquo.saml.redirect.error.endpoint

URI redirect for an unsuccessful Abiquo login using SAML SSO. This has to be set to a queryparameter "?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
colourBlue
title

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

Status
colourBlue
title

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

Status
colourBlue
title

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. For multiple identity providers, use a comma separated list

Yes

Status
colourBlue
title

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 comma-separated list with the binding names

No
Default: POST, Artifact

Status
colourBlue
title

abiquo

admin

Status
colourYellow
titlesaml 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
colourBlue
title

abiquo

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
colourBlue
title

abiquo

admin

abiquo.saml.keys.signing.alias

The alias of the key to use for signing SAML Requests
Accepts: any string

Yes

Status
colourBlue
title

abiquo

admin

abiquo.saml.keys.signing.password

The password of the key to use for signing SAML Requests
Accepts: any string

Yes

Status
colourBlue
title

abiquo

admin

abiquo.saml.keys.encryption.alias

The alias of the key to use for encryption of SAML Requests
Accepts: any string

Yes

Status
colourBlue
title

abiquo

admin

abiquo.saml.keys.encryption.password

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

Yes

Status
colourBlue
title

abiquo

admin

abiquo.saml.keys.metadata.sign

Indicates if the SAML Requests must be signed.
Accepts: a boolean

No
Default: false

Status
colourBlue
title

abiquo

admin

Status
colourYellow
titlesaml admin

abiquo.saml.binding

Indicates the binding profile to allow.
Accepts: the SAML binding profile's URN

Yes

Status
colourYellow
titlesaml 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
colourYellow
titlesaml 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
colourYellow
titlesaml 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
colourYellow
titlesaml 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
colourYellow
titlesaml 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

Status
colourYellow
titlesaml admin

abiquo.saml.attributes.user.email.claim

Indicates which attribute must be read in order to find the user email.
Accepts: any string

No
Default: EmailAddress

Status
colourYellow
titlesaml 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

No
Default: false

Status
colourYellow
titlesaml 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
colourBlue
titleabiquo 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
colourBlue
titleabiquo admin