Abiquo OpenID integration reference

1 Diagram of the Abiquo OpenID Connect integration
2 How Abiquo maps external enterprises to Abiquo enterprises
- 2.1 Enterprise mapping by name
- 2.2 Enterprise mapping by enterprise property
3 How Abiquo maps OpenID role claims to Abiquo roles
4 Table of Abiquo OpenID Connect properties
5 UI properties for the Abiquo OpenID Connect integration

Diagram of the Abiquo OpenID Connect integration

The following sequence diagram shows how the different endpoints are used from a user and relying party perspective. The diagram depicts the interactions between all parties involved in the OpenID Connect protocol.

OpenID interaction diagram

How Abiquo maps external enterprises to Abiquo enterprises

When the OpenID Connect server returns user data, it includes the enterprise claim, which is the Abiquo tenant enterprise that the Abiquo user should belong to.

If Abiquo cannot find the enterprise, it will not allow the user to log in.
If the user account does not exist, Abiquo will create it in the enterprise.
If the user account exists in another enterprise, Abiquo will move it to the one assigned by the OpenID Connect server.

Abiquo can look up the enterprise in Abiquo by enterprise name or by an enterprise property.

Enterprise mapping by name

By default, Abiquo will look up the enterprise by its name, as shown in the following diagram.

You will configure the abiquo.openid.enterprise-claim property with the name of the enterprise claim in the OpenID user data.

If you are not permitted to name the enterprise to match the role claim, you can map an OpenID enterprise to an Abiquo enterprise by enterprise property.

Enterprise mapping by enterprise property

If you cannot name your Abiquo enterprises with the same names as in the enterprise claims of your OpenID connect server, you can use an enterprise property instead, as shown in the following diagram.

To map an OpenID enterprise to an Abiquo enterprise by enterprise property:

Create or edit an Abiquo enterprise
Create an enterprise property with the key configured in the abiquo.openid.enterprise-property in abiquo.properties.
For example, for abiquo.openid.enterprise-property = domain, create an enterprise property called domain.
Set the value of this property to the value of the enterprise claim for this tenant, for example abiquo.com

In this example, when the authorization server returns the enterprise claim, Abiquo will look for all enterprises with a domain property. It will find the one with the value that matches the value returned by the OpenID Connect server. So when the OpenID Connect server returns the value abiquo.com in the enterprise claim, Abiquo will select this enterprise.

How Abiquo maps OpenID role claims to Abiquo roles

When the OpenID Connect server returns user data, it includes the role claim, which is a list of the external roles/permissions for the user.
Later you will configure the abiquo.openid.role-claim property with the name of the role claim in the OpenID user data.
To create a user, Abiquo will try to find an existing Abiquo role with a value of the External role attribute to match the role claim value.

A user's external roles must map to one Abiquo role, which can be a global role, or a local role in their enterprise.

Table of Abiquo OpenID Connect properties

To enable the OpenID Connect mode, configure the following properties in Abiquo:

Property	Description

Property	Description
OpenID Connect server configuration
abiquo.auth.module	The Abiquo authentication module. Must be: `openid`
abiquo.openid.cookie.maxage	After OpenID authentication flow, the API redirect adds a cookie with the access_token and the id_token. The expiry of the OpenID authentication cookie in seconds. A negative value means that the cookie is not stored persistently and will be deleted when the web browser exits. A zero value causes the cookie to be deleted Default: 30
abiquo.openid.cookie.refreshtoken.include	If true, the OpenID authentication cookie will also contain the refresh token. Default: false
abiquo.openid.target	The URL where the user will be redirected from the Identity Server upon successful authentication. Something like `http://<abiquo ui host>/ui/#/dashboard`
abiquo.openid.role-claim	The name of the claim returned by the authorization server that contains the names used to map the user permissions to an Abiquo role
abiquo.openid.enterprise-claim	The name of the claim returned by the authorization server that contains the names used to map the Abiquo enterprise where the user belongs
abiquo.openid.enterprise-property	(Optional) If present, Abiquo will try to find an enterprise that has a property with the name configured in this property. It will use its value to match the "enterprise claim" when resolving the user's enterprise. If absent, Abiquo will just look for an enterprise with the name returned in the "enterprise claim".
abiquo.openid.issuer	The OpenID Connect authorization issuer.
abiquo.openid.authorization.endpoint	The OpenID Connect authorization endpoint. This endpoint must be accessible from the user's browser
abiquo.openid.token.endpoint	The OpenID Connect token endpoint. This endpoint must be accessible from the Abiquo server.
abiquo.openid.userinfo.endpoint	The OpenID Connect user info endpoint. This endpoint must be accessible from the Abiquo server.
abiquo.openid.jwks.endpoint	The OpenID Connect JWKS endpoint. This endpoint must be accessible from the Abiquo server.
abiquo.openid.endsession.endpoint	(Optional) If configured, Abiquo will attempt to perform a global logout performing a request to this endpoint. This is part of the Session Management optional spec. This endpoint must be accessible from the user's browser.
OpenID Connect client configuration
abiquo.openid.client.name	The name of the client that has been registered in the OpenID Connect server for the Abiquo platform.
abiquo.openid.client.id	The ID of the client that has been registered in the OpenID Connect server for the Abiquo platform.
abiquo.openid.client.secret	The secret of the client that has been registered in the OpenID Connect server for the Abiquo platform.
abiquo.openid.client.scopes	Comma separated list of scopes to request during authentication. Must have, at least: `openid,profile,email`. Also supports: `phone`.
abiquo.openid.client.redirect-uris	Comma separated list of allowed redirect (callback) URIs used during the authentication flow. Must be: `http://<api endpoint>/api/openid_connect_login`
abiquo.openid.client.acr-values	Space separated values for the ACR values to send to OpenID Connect Server when authenticating. They will be validated if `acr-validation` property is `true` (default value).
abiquo.openid.client.acr-validation	Activates the validation of ACR values. The default value is `true`

UI properties for the Abiquo OpenID Connect integration

Configure the OpenID Connect client UI properties in the client-config-custom.json file.

Property	Description

Property	Description
client.openid.enabled	Deprecated in Abiquo 4.7.1
client.openid.skip.login.view	Deprecated in Abiquo 4.7.1 for UI 5. By 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.
client.skip.login.view	By 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.
client.auth.module	Abiquo login modules to use with options for Basic Auth (default), Open ID, and SAML. See `client-config-default.json` for examples