Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

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.


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. 

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



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


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


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


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


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


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



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



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



12. Optionally add multiple identity providers for SAML

Abiquo 5.2.1 introduces multiple identity providers (IdPs) for the SAML integration. 

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. 

In this version, Abiquo will use 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:

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

      (warning) Do not use a comma , in a key or a value
      (warning) 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.

When you enable this feature, Abiquo will change the XML security metadata of the Abiquo application. It 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





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

(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

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

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

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 comma-separated list 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.passwordThe 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 key to use for signing SAML Requests
Accepts: any string

Yes

ABIQUO ADMIN

abiquo.saml.keys.encryption.alias

The alias of the key to use 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 a unique user; 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 to 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. 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

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 be read in order to find the user email.
Accepts: any string

No
Default: EmailAddress

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

No
Default: false

SAML ADMIN

abiquo.saml.metadata.identityprovider.default.idSets the default SAML IdP
Accepts: The entityID attribute of the default IdP from its metadata		Yes

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

ABIQUO ADMIN



  • No labels

Copyright © 2006-2024, Abiquo Holdings SL. All rights reserved