Abiquo OpenID Connect integration

Introduction

This page describes the Abiquo integration with OpenID Connect. This integration lets you use single sign on authentication and federated authorization features.
The integration implements the core spec, as well as some optional features, such as the  RP-Initiated-Logout, from the optional Session Management spec.
The scope of this integration does not include discovery, dynamic registration, and other optional features.

Basic OpenID Connect workflow

The following diagram shows the basic authentication and authorization workflow when you use the OpenID Connect integration.

Open

OpenID workflow

1. Users access the Abiquo portal, and it redirects them to the OpenID Connect server

2. Users enter their credentials to log in to the OpenID Connect server. The OpenID Connect server will display the consent screen that describes the permissions that Abiquo is requesting and the information it needs to access.

   1. The user credentials are never exposed to Abiquo

3. When the users are successfully authenticated and grant consent, the OpenID Connect server redirects the user back to Abiquo with the following tokens:

   1. ID token - A JWT token containing the information about the user.

   2. Access token - An OAuth2 token that provides access to the application resources on behalf of the user.

   3. Refresh token - An optional token that can be used to refresh the access token when it expires.

4. Abiquo uses the access token to request information about the logged user (permissions, etc) and will create the corresponding user in the Abiquo database.

5. Users use the access token to access the Abiquo platform, including the Abiquo API

• At any time, users with the refresh token can call the Abiquo API to refresh the access token.

• If the global logout is configured, when users log out from the Abiquo platform they will be signed out from the OpenID Connect server.

How Abiquo works in OpenID Connect authentication mode

When Abiquo is in abiquo authentication mode, Abiquo authenticates and obtains user authorization from the Abiquo database.
When Abiquo is in openid authentication mode, Abiquo authenticates and obtains user authorization from the OpenID Connect server.

In openid authentication mode, Abiquo behaves as follows.

• Abiquo creates an Abiquo OpenID user automatically, when the following conditions are met:

  1.  The user successfully authenticates with the OpenID Connect server; AND

  2.  Abiquo finds an Abiquo enterprise and user role that matches the one from the OpenID user data

• Every time the user logs in, Abiquo synchronizes user data with the OpenID Connect server.
  This can overwrite any changes you make to the Abiquo user account.

  • If a user has switched enterprises, then when they log in, they will be returned to their enterprise from OpenID

• Abiquo disables login for users with non-OpenID accounts

  • This includes the main cloud admin user

• Abiquo disables features associated with normal authentication, e.g. Abiquo two-factor authentication, Abiquo password reset

  • The OpenID Connect server should provide this type of feature when authenticating users

Configure OpenID Connect integration for Abiquo

Configure your OpenID connect server. In this example, we will use Keycloak.

1. Create an IDP with OpenID Connect v1.0

This is for a Keycloak server. Create a Realm with an OpenID Connect endpoint.

1. Access your Keycloak server with admin credentials.

2. Select the realm you want to use, or create a new one in the top-left drop-down.
   In this example some URIs use the master realm - please change it to your realm.

3. Go to Identity Providers → OpenID Connect v1.0

4. In the Add OpenID Connect provider dialog:

   1. Use the default Redirect URI

   2. Enter an Alias

   3. In Discovery Endpoint enter http://{$YOUR_KEYCLOAK_SERVER}/realms/master/.well-known/openid-configuration

   4. Enter a Client ID

   5. Enter a Client Secret

   6. Select Add

2. Create a client to connect to Abiquo

Create a client that will connect to Abiquo.

1. Go to Clients → Create client

2. Enter a Client ID

3. Enter a Name

4. Select Next

5. Select Next

6. For Login settings enter:

   1. In Root URL enter https://{ABIQUO_SERVER_FQDN} 

   2. In Home URL enter https://{ABIQUO_SERVER_FQDN}/ui/#/dashboard

   3. In Valid redirect URIs enter https://{ABIQUO_SERVER_FQDN}/*

   4. In Web origins enter https://{ABIQUO_SERVER_FQDN}

3. Configure user claims

The user claims will configure a user’s enterprise and role in Abiquo.

1. Go to Realm roles ⇾ Create role and enter a role name that will match an external role in your Abiquo environment.

2. Go to Groups ⇾ Create group and enter a name that will match an enterprise in your Abiquo environment

3. Go to Users ⇾ Add user and enter Username, Email, First name and Last name.

4. Select Join groups and add the group created in step 2.

5. Select Client scopes → Create client scope:

   1. Enter a Name

   2. In Type select Default

   3.  Select Save

6. Select Mappers tab ⇾ Configure a new mapper

7. Select Group membership 

   1. Enter a Name 

   2. Enter a Token claim name (this name will be used later in abiquo.properties to match the enterprise)

   3. Disable Full group path and Add to ID token

   4. Select Save

8. Add a new mapper by configuration in this client scope and select User realm role 

   1. Enter a Name

   2. Enter Token claim name (this name will be used later in abiquo.properties to match the role)

   3. Disable Add to ID token

   4. Select Save

9. Select Clients ⇾ enter in Client created previously

10. Select Client scopes tab ⇾ Add client scope

11. Add the client scope created in step 5 as default

4. Configure Abiquo

Configure Abiquo to use the OpenID Connect server.
When you configure Abiquo, it should be in the default authentication abiquo mode

1. Log in as the cloud admin user, and configure this user

2. Create or edit an Abiquo enterprise and set the Name to match the value of the enterprise claim in OpenID.
   In the Keycloak example above, this was the group name.
   If you are able to name the enterprise to match the role claim, see the section on how to map an OpenID enterprise to an Abiquo enterprise by enterprise property.

3. Create, clone or edit an Abiquo role. For the External roles, enter the list of external roles/permissions from the OpenID user's role claim.
   A user's external roles must map to one Abiquo role.
   In the Keycloak example above, this was the Realm role.

   Open

   

4. On the Abiquo API server, configure the abiquo.properties for OpenID Connect

   abiquo.auth.module = openid abiquo.openid.target = https://{ABIQUO_SERVER_FQDN}/ui/#/dashboard abiquo.openid.role-claim = (User Realm Role Token Claim Name) abiquo.openid.enterprise-claim = (Group Membership Token Claim Name) abiquo.openid.issuer = http://{KEYCLOAK_SERVER}/realms/master abiquo.openid.authorization.endpoint = http://{KEYCLOAK_SERVER}/realms/master/protocol/openid-connect/auth abiquo.openid.token.endpoint = http://{KEYCLOAK_SERVER}/realms/master/protocol/openid-connect/token abiquo.openid.userinfo.endpoint = http://{KEYCLOAK_SERVER}/realms/master/protocol/openid-connect/userinfo abiquo.openid.jwks.endpoint = http://{KEYCLOAK_SERVER}/realms/master/protocol/openid-connect/certs abiquo.openid.client.name = (Specified in Create OpenID Connect v1.0 IdP) abiquo.openid.client.id = (Specified in Create OpenID Connect v1.0 IdP) abiquo.openid.client.secret = (Specified in Create OpenID Connect v1.0 IdP) abiquo.openid.client.scopes = openid,profile,email, (client scope name) abiquo.openid.client.redirect-uris = https://{ABIQUO_SERVER_FQDN}/api/openid_connect_login abiquo.openid.client.acr-validation = false

    

5. On the API server (or separate UI server), in the /var/www/html/ui/config folder, edit the client-config-custom.json file and add the following configuration.

   { "config.endpoint":"https://{ABIQUO_SERVER_FQDN}/api", "client.skip.login.view": "true", "client.login.modules": [ { "label": "Open ID", "description": "Open ID login", "templateUrl": "modules/login/authenticationmodules/openid/partials/openidloginview.html", "cookieName": "ABQOIDCTOKENS" } ] }

5. Configure SameSite cookie flag

On the Abiquo API Server, set the abiquo.login.samesite property to control the value of the SameSite flag of the login cookie. See https://abiquo.atlassian.net/wiki/spaces/doc/pages/311375440 and search for .samesite. For our test server, we set

6. Optional OpenID Connect logout

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.

7. Optional ACR validation

In an OpenID Connect integration, the authorization request can contain a list of authentication modes that the server should show to the user.
This is a list of acr-values and it's a configuration of the OpenID Connect Server.

So Abiquo could request that using the acr-values system property.

Also, the response tokens could contain the acr-values used by the user to authenticate.
if the acr-validation  property is set, Abiquo can validate that the acr-values are the requested ones, and fail the authentication process if they aren't.

Configure API clients

In OpenID Connect mode, Abiquo disables basic authentication, so in order to authenticate with the API , you can use an access token.

To obtain an access token:

1. Manually log in to the platform

2. When you are redirected back to the Abiquo console, you'll find the access token and refresh token in the URI.

Once you have the token, you can issue requests to the API by providing the following HTTP header:

Refreshing access tokens

Access tokens have an expiration, so at a certain point in time they will stop working.
When this happens, the user can use a refresh token if it 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.

Troubleshooting

The OpenID login process may return an error message for example due to a delayed login or timeout.
To prevent this, for Internet Explorer cookies, in server.xml on Abiquo Tomcat, the <Host> section should contain an <Alias> section with the domain of the web server (where users access the UI).
And the default Java session timeout was changed to 30 minutes to ensure user delays during OpenID login will not result in further errors.