Documentation

No results
    gitHub

    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:

    Collibra CSRF Token mismatch

     

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

    Collibra REST API security config

     

     

    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.

     

    Collibra REST API security config console

     

     

     

     

    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:

    Collibra Mapping Domain

     

     

    Username and password

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

    Collibra connection settings

    as well as authentication credentials:

    Collibra authentication

     

    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:

    Collibra JWT flow diagram

     

    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:

    Image

     

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

    Collibra JWT - Windows Firewall

     

    and Identity Provider permissions confirmation in your browser:

    Collibra JWT - IDP permissions confirmation

     

    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 - IdP browser confirmation

    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.

     

    Collibra JWT - Console config

     

    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

     

    Collibra JWT Auth - Web redirect URL

     

     

     

    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.  

    Collibra JWT - Client ID  Endpoint Metadat

     

    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:

    Collibra JWT - Add Client Secret

     

    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.

     

    Collibra JWT - Client Secrets

     

    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. 

     

    Collibra JWT Okta Applications

     

    with the options:

    Collibra JWT Okta create new app

    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.

     

    Collibra JWT Okta - App grant

     

     

     

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

    Collibra JWT Okta - Add Auth server

     

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

    Image

     

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

     

    Collibra JWT Okta - Client Secret

     

     

     

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

    Collibra JWT Okta - Metadata URL