Author: Ignasi Barrera
This page describes the Abiquo integration with OpenID Connect available in Abiquo v3.8.6+. This integration allows Abiquo to leverage single sign on authentication and federated authorization features. The integration targets the core spec, but also implements some optional features such as the RP-Initiated-Logout from the optional Session Management spec. Discovery, dynamic registration and other optional features are out of the scope of this integration.
Changes to the OpenID integration in Abiquo 3.10.7
To retrieve the user's phone number from the OpenID system to the corresponding Abiquo user attribute, edit the abiquo.properties file and add "phone" to the value list of the abiquo.openid.client.scopes property. Abiquo does not validate the phone number
The following diagram shows the basic authentication and authorization workflow when using the OpenID Connect integration:
When Abiquo is in normal authentication mode, Abiquo authenticates and obtains user authorization from the Abiquo database. In contrast, when the platform is in OpenID Connect mode, Abiquo authenticates and obtains user authorization from the OpenID Connect server. In OpenID mode, Abiquo behaves as follows:
This is an overview of the steps to configure the OpenID Connect Integration
Configure the cloud admin user with Abiquo in normal authentication mode. Remember that Abiquo will disable this user when you enable OpenID Connect authentication mode.
In OpenID Connect authentication mode, when a user successfully authenticates through the OpenID Connect server, Abiquo will receive OpenID user data. Abiquo will try to match the user data to the following in Abiquo:
To enable Abiquo to match the user, you must work in Abiquo to map the Abiquo enterprise and role to the OpenID user data. Work in normal authentication mode as the cloud admin user. If Abiquo cannot find the role and enterprise, it will not create the OpenID user.
The OpenID Connect server will return user data, including a list of the external roles/permissions for the user, which is called a role claim. Abiquo will identify the role claim in the OpenID user data using the name you configure with the abiquo.openid.role-claim property. Abiquo will try to find an existing Abiquo role with the same LDAP attribute data as the role claim.
To map OpenID roles to an Abiquo role:
Remember that a user's external roles must map to one local role in their enterprise and/or one global role.
The OpenID Connect server will return user data, including the tenant that a user should belong to, which is called an enterprise claim. Abiquo can look up this enterprise in Abiquo by enterprise name or by enterprise property. 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 will obtain the enterprise claim defined by the abiquo.openid.enterprise-claim property. Abiquo will try to match the enterprise claim to the enterprise name if the abiquo.openid.enterprise-property property IS NOT SET in abiquo properties. Otherwise, it will try to match the value of the enterprise claim to the value of the enterprise property specified by the abiquo.openid.enterprise-property property.
Map external enterprises to Abiquo enterprises according to the lookup method you configured for your platform.
To map an OpenID enterprise to an Abiquo enterprise by enterprise name, just name the enterprise with the value in the enterprise claim.
To map an OpenID enterprise to an Abiquo enterprise by enterprise property:
When the authorization server returns the enterprise claim, Abiquo will look for all enterprises with a "domain" property, and find the one with the value that matches the value returned by the OpenID Connect server. In this example, when the OpenID Connect server returns the value "abiquo.com" in the enterprise claim, Abiquo will select this enterprise.
Register Abiquo as a client application in the OpenID system and obtain the client credentials: client name, client id and client secret. You will need to configure these in abiquo.properties in the next step.
To configure OpenID Connect in abiquo.properties:
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.
To enable the OpenID Connect mode, configure the following properties in Abiquo:
|OpenID Connect server configuration|
|abiquo.auth.module||The Abiquo authentication module. Must be: openid|
|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|
(Optional) If present, Abiquo will try to find an enterprise that has a property with the name configured in this property, and 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.|
Comma separated list of scopes to request during authentication. Must have at least: openid,profile,email. Abiquo 3.10.7 added support for 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|
Register the Outbound API as an OAuth application (for Outbound API user or admin user) and use the tool to obtain the OAuth access token. Configure credentials in abiquo.properties and remove any old credentials properties
In OpenID Connect mode, the normal authentication (using HTTP Basic Authentication) is disabled, so you must configure the Outbound API credentials as OAuth tokens. To do this:
If the OpenID Connect server implements the Session Management extension, you can configure the Abiquo platform to issue a logout to the OpenID Connect server when the user logs out from the platform. This is optional because users might not want to be logged out from all services when logging out from Abiquo.
To enable the global logout, configure the abiquo.openid.endsession.endpoint property to point to the end session endpoint, as defined by the RP-Initiated Logout spec.
Configure the OpenID Connect client UI properties in the client-config-custom.json file.
|client.openid.enabled||Boolean value indicating if OpenID Connect mode is enabled. Set to true.|
|client.openid.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.|
In OpenID Connect mode, Abiquo disables Basic Authentication, so in order to authenticate with the API (or against the Outbound API endpoint), you can use an access token.
Abiquo still supports authentication using the session cookie or Abiquo OAuth applications as before
To obtain an access token:
Once you have the token, you can issue requests to the API by providing the following HTTP header:
Access tokens have an expiration, so at a certain point in time they will stop working. When this happens, the user can use the refresh token that was returned during authentication to request a new access token. Refresh tokens also expire, but have a significantly higher expiration (default is one week). Some OpenID Connect providers issue new refresh tokens every time an access token is refreshed, so the refresh mechanism can be used without limit.
To request a new access token using a refresh token, an HTTP request must be issued to the "openid_conect_refresh" Abiquo API endpoint, passing the refresh token as a query parameter:
Note that the refresh token request does not require authentication. This is because it is meant to be used when the access token is expired, so the Abiquo API just passes the refresh token to the authorization server and lets it verify the validity of the token and the identity associated with it.