Connection and authentication

To properly connect Hackolade Studio to your Collibra instance, there are requirements for setup on the Collibra side, and there are requirements for information to be configured for connection and authentication on the Hackolade Studio client side.

Collibra setup Requirements

The requirements on the Collibra side, for the Hackolade Studio integration to function properly, include REST API security configuration and user rights.

Security configuration

By default, the Collibra configuration is correct, and no action should be required.  But your administrator may have changed one parameter that would prevent our REST API integration.  If you encounter the error message below about CSRF token mismatch:

 

then an adjustment is required in the Collibra console, as per the Collibra documentation.

 

 

You may need to ask your administrator to go to https://console-\<your organization>.collibra.com/#/infrastructure > Environments > your instance > Data Governance Center > Configuration tab > 15 Security Configuration > 15.3 REST > 15.3a Limited CSRF and set it to False.

 

 

 

 

 

User rights

In order to feed data model information to the Collibra instance, it is assumed that you have sufficient credentials to do so.  If not, please contact your Collibra administrator.

To successfully import a Hackolade model into Collibra, a user should have the author's license type. The role that is assigned to the user should have been provided with the following permissions:

 

• For global role and permissions:

  • System administration - (This is necessary to apply the custom Hackolade configuration: attributeTypes, relationTypes, scope...)

• For resource role and permissions:

  • Asset:

    • Add

    • Attribute:

      • Add
      • Remove
      • Update

  • Attachment:

    • Add

  • Domain: (This is necessary for views and work with Hackolade Mapping Domain)

    • Add
    • Remove
    • Update

 

We also recommend assigning a user with the above permissions to the parent community of the target domain. It is needed to create/update/delete Hackolade Mapping Domain.

 

The Hackolade Mapping Domain is used to represent links between view columns and columns in tables, for example:

 

 

Username and password

To connect to the Collibra instance, you must first specify connection settings:

as well as authentication credentials:

 

JWT JSON Web Token authentication with Single Sign-On

Hackolade Studio also allows authentication using JWT tokens, based on the configuration allowed by Collibra.  In this configuration, OAuth and JWT are used together: when the authentication server verifies a user’s credentials, it uses OAuth to transmit the user details to the client application.  OAuth is used for authorization, while JWT is used for authentication and exchanging information

 

JSON Web Tokens (JWT) are a compact and self-contained open industry standard for authentication and information exchange between two entities, typically a client (in this case, your Hackolade Studio client) and a server (the Collibra instance).  A JWT contains a cryptographically signed JSON object with information to be shared, so that clients or malicious parties cannot modify JSON content (also known as JWT claims).

 

 

Open Authorization (OAuth) is an open standard for token-based authentication over public networks.  OAuth allows third-party services to use end-user account information without exposing the user’s account credentials to a third party.  It acts as an intermediary on behalf of end users, providing access tokens to third-party services authorized to share certain account information. The process of obtaining a token is called the authorization flow.  Oauth maintains a session state on the server and uses a unique token to grant access to the user’s resources. It enables a user to grant a third-party application access to their resources on another site without giving away their username and password.

 

Although JWT and OAuth (in its version 2) serve different purposes, they are compatible and can be used together. Because the OAuth2 protocol does not specify a token format, JWT can be incorporated into OAuth2 usage.

 

In the Collibra diagram below, Hackolade Studio is the Customer Client:

 

Your administrator will have set things up with an Identity Provider such as Microsoft Entra ID (ex-Azure AD), or Okta.  See below for more details, for each IdP.

As a user, you must first setup the connection settings with parameters provided by your administrator.  This dialog will vary dynamically depending on the options chosen:

 

Then, provided that the parameters are correct, you should accept the authorization prompts such as Windows Firewall: 

 

and Identity Provider permissions confirmation in your browser:

 

and your authentication credentials if you have not done so previously.  Once authenticated, your browser will display this Identity Provider permissions confirmation message:

Collibra JWT configuration

This configuration should have been performed already by your administrator in the Collibra Console ( https://console-yourOrg-collibra.com ).  The Collibra documentation provides the necessary instructions.

 

 

In 15.9.a, JSON Web Key Set URL, the entry includes the Directory (Tenant) ID

In 15.9.c JWT issuer, the entry also includes the Directory (Tenant) ID

In 15.9.e JWT audience, the entry is the Application (Client) ID

 

Azure AD / Microsoft Entra ID

Azure allows to different grant options: Authorization Code Flow and Client Credentials Flow.  You must use the grant type used in your Collibra JWT configuration settings.  If it is set up to use the Entra ID Single-Sign On, you must use the grant type Authorization Code.

 

A Collibra JWT application should have been registered in Azure by your administrator as an authorized application.  To access the parameters needed to be copied into the Hackolade connection settings, in the Azure Portal console, go to Microsoft Entra ID > Manage > App registrations > All applications, then in the Collibra JWT application, go to Overview and choose Endpoints:

If users authenticate using the "Authorization code" grant type, they must specify the redirect URI as the destination for returning authentication responses (tokens) after successful authentication. For Hackolade Studio, this URL must be: http://localhost:30424/oauth. 

 

 

 

 

Next, you must fetch the Client ID and the Metadata URL and paste them in the appropriate fields in the connection settings dialog.  You can find those 2 pieces of information in the Azure Portal.  

 

Application (client) ID --> Client ID

OpenID Connect metadata document --> Metadata URL

 

Make sure to click the button "Use" which will pre-fill the rest of the fields below in the Connection Settings form.

 

Then go to Manage > Certificates & Secrets and choose Client secrets tab.  Add a new client secret, enter a description and choose the desired expiration:

 

Make sure to copy the value of the secret, keep it in a safe place, and paste it in the Client Secret field of the Connection Settings form.

Note that the Client Secret is only visible at the time of creation.  Once you leave this page, it will be hidden, so make sure to save it before closing the page. If you revisit this page after the configuration is already created, the value will be hidden.

 

 

If necessary, your administrator may instruct you to adjust the Scopes entries to match the configuration in Collibra.  By deafult, the entry is assembled wuth "<clientID>/.default openid offline_access"

 

Okta

A Collibra JWT application should have been registered in Okta by your administrator as an authorized application. 

 

 

with the options:

To access the parameters needed to be copied into the Hackolade connection settings, in the Okta console, go to Microsoft Entra ID > Manage > App registrations > All applications, then in the Collibra JWT application, go to Overview and choose Endpoints:

 

Only the "Authorization Code" flow is enabled by default, but this can be configured in the application settings in OKTA (Applications -> {CollibraIntegrationAppName} -> General tab). Usually, the administrator setting up JWT authentication has this information.

 

 

 

 

Auth URL and Access Token URL:Security -> API -> Your Authorization Server (or Default Server) -> Metadata URI

 

Client ID: Applications -> {CollibraIntegrationAppName} -> General tab. See the Client ID field.

 

Client Secret: Applications -> {CollibraIntegrationAppName} -> General tab. See the Client Secrets block.

 

 

 

 

Copy the Metadata URL and paste it in the corresponding Connection Settings fields