Setup CI HUB in censhare

The CI HUB integration is part of all censhare web-packed installations. This article explains the necessary steps to set up the integration.

Prerequisites

The CI HUB integration requires a web-packed censhare installation with Keycloak as the authentication server. For more information, see RPM installation tutorial. Please make sure that you added the correct route forwarding for the CI HUB integration into the proxy configuration.

Introduction

The CIHUB module provides the REST interface and schema definitions on the censhare Server. Optionally, you can configure a global query to filter the assets that can be accessed via the CI HUB integration (for example: asset types, domains or output channels). By default, no query is defined and all assets are accessible. This part of the configuration is done in the censhare Admin Client.

The schema definitions are part of the CIHUB module and stored in the ../censhare/censhare-Custom/censhare-Server/app/modules/cihub/schemas/ sub-directory of the CI HUB module configuration.

Configure the CI HUB application client in Keycloak

The CI HUB application client authenticates users at CI HUB. You must configure the redirects from the Keycloak client to the censhare Server, the censhare client localhost, and CI HUB server.

1. Log in to the Keycloak Administration Console.

2. At the top of the side navigation, select the censhare realm.

3. In the side navigation, select Clients.

4. At the top right of the Clients table, click Create.

5. In the Client ID field, enter cihub and click Save.

6. Configure the client. 

   

   Use our cihub.json configuration file to create this configuration. To do so, click Select file in the Add Client dialog and upload the configuration.

   Or configure the appropriate settings individually as follows:

1. On the Settings tab, go to Valid Redirect URIs and add the following URIs:
   • https://ci-hub.azurewebsites.net/api/v1/auth/login/censhare
   • http://localhost:8080/api/v1/auth/login/censhare
   • https://CENSHARE-SERVER/*

Additional info on configuring working timeouts for CI HUB

The CI HUB integration has some specific imposed by the 3d-party provider. When configuring timeouts in Keycloak, please keep in mind the following.

As long as the CI HUB tab is opened and connected to the censhare Server, the user session is considered not idle and kept active endlessly (see a workaround below to avoid this). First when the CI HUB tab is disconnected, or closed, or the whole application is closed, the session is considered idle. From that point in time on, the  countdown for the Client Session Idle setting in Keycloak starts running. During that time period, the user can open the CI HUB tab again and connect directly, without a new login. After that time, they need to log in again.

 If Client Session Idle is set to “Never Expires”, the login might not be ever required again! 

A workaround to avoid eternal sessions, is to set up the "Client Session Max" in Keycloak. It logs out the user after the specified amount of time passed since the last login, even if the session is active, i.e., the user is interacting with the application. This is not user-friendly, indeed, and needs to be considered only for security reasons. 

Get secret for Keycloak client

In censhare Server with censhare WP, every request to the API of the censhare server must be authenticated, including the REST API of the CIHUB module. For this purpose, an access token is added to each request. This access token is issued by the Keycloak server. If you want to develop custom schemas or test your CORS header, you need this access token. 

To get the secret, do the following:

1. Login into the Keycloak Administration Console.
2. Go to the Clients section on the left side.
3. Open the cihub client.
4. Go to the Credentials tab.
5. Copy the client secret value in the Secret field.

Register censhare Server at CI HUB

To connect the censhare Server to the CI HUB Server, you must register the censhare Server. The following is required for the registration:

• Keycloak client ID
• Keycloak secret

Configure CI HUB module

1. In the censhare Admin Client, open Configuration/Modules/CIHUB and double-click CIHUB Integration to add a new configuration.
2. In the General setup section, select Enabled.
3. In the Dataset section, in Configuration type, select Generic query. Now, the Asset filters section displays. You can define an optional query with common parameters or asset flag parameters. For more information, see Configure asset filters.
4. In the Data changes behavior section, you define how censhare handles incoming updates from the CI HUB server:
   • Update as new version: Select to create a new asset version in censhare.
   • Default domain: New assets are stored to the default domain.
   • Default domain 2: New assets are stored to the default domain 2.
   • Primary output channel: Assign an output channel to new assets.
5. In  the API and Schema Registry section,
   • Resource key of schema:  Do not change (default: cihub-schema)! 
   • Default page size: 

   • Allowed origins (CORS):

     CORS...

     Cross-Origin Resource Sharing (CORS) is an HTTP-header-based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources. Read more...

     Add the CI HUB server URL and the localhost URL:  The URL of the CI HUB server is provided by CI HUB. The default URI of the censhare client on a local user system is http://localhost:8080.

   • CORS max age: Set an optional value for the Access-Control-Max-Age header. This value sets the caching of CORS preflight responses in seconds. For example: 600 allows to cache responses for 10 minutes.
6. In the Dynamic Image Cache section, you can configure an image cache for every storage item type to reduce the API requests.
   • Max age: 
   • Cache size: 
   • Source storage item: 
   • Autodetect type: 
   • Default format: 

7. In the Request logging section, you can configure log entries for API requests. 

   

   Use only for developing and testing of custom schemas!

8. In the Webhooks section, you can configure the URL and authentication for trigger events that are sent as webhooks to the CI HUB server.
   • Base URL: 
   • Timeout:
   • Connection timeout: 
   • HMAC:
9. Click OK to save your configuration and close the dialog.
10. Update the server configuration.
11. Synchronize remote servers if you have a Master-Remote-Server setup.

12. To check if CORS is enabled, execute the following command:
    

    BASH

    curl -v -X OPTIONS 'https://CENSHARE_SERVER/hcms/v2.0/entity/presentation' \ 
    -H 'Origin: https://myorigin' \ 
    -H 'Authorization: Bearer ACCESS_TOKEN'

    Notes

    (1) Replace CENSHARE_SERVER with the domain name of your censhare Server.

    (2) Replace with the Keycloak access token. To generate a token, see  Setup CI HUB in censhare#Get secret for KeyCloak client.

    

    Bypass CORS

    If you experience connection problems related to CORS, you can enter "*". The CIHUB module then accepts any foreign origin. For security reasons, this setting must not be used on production systems!

General server configuration

To enable deep links, the general configuration of the censhare Server must be adapted as follows:

1. In the censhare Admin Client, open Configuration/Server/General.

2. In the JVM properties section, look for com.censhare.web.web-client-url.

   

   If the property does not exist, switch to admin mode, click  to add a new entry, and enter the property name.

3. As property value, enter the URL of your censhare Web application. Usually, this URL looks as follows: https://example.censhare.com/cihub/client/.

   

   If you are not sure, you can test the URL in a web browser. It opens the censhare Web login screen.

4. Next to the entry, select Enable to activate the property.
5. Click OK to save the configuration and close the dialog.
6. Restart the censhare Server.

Configure webserver

censhare WP uses an nginx webserver that handles all requests from and to external services. To avoid network errors when handling large files, we recommend setting the maximum file size for uploads to 10GB using the client_max_body_size directive of nginx.

1. Open a terminal and go to the nginx configuration on env:

   CODE

   /etc/nginx/nginx.conf

2. Set the max file size:

   CODE

   client_max_body_size 10 GB

Next steps

To use the CI HUB integration with Adobe CC applications, users must install the CI HUB connector plugin on their computers, register with CI HUB and connect to the censhare Server. For more information, see the CI HUB user guide.