Set up 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.

Obtain a CIHUB license

You will need to obtain the CIHUB license directly from the third-party provider. Please refer to their official resources. 

After buying the license, make sure that the license key is made available to the end users as they will need it later. 

Configure Cloud Gateway

Upgrade to proper Cloud Gateway version

Previously, a lot of back-and-forth communication between Censhare and CIHUB had to happen to make this integration work for you. Recently, a new, simple self-registration has been introduced, which is now also the only way to start using the integration. However, you will need to upgrade your Cloud Gateway. Which minimum version you need, depends on the Server version. 

Below you will find the compatibility matrix.

Earlier Censhare versions won't work with this integration. 

Well-known API endpoint

You will need to make sure the following endpoint, based on the RFC5785 standard (RFC8414 for OAuth2 that Keycloak uses).

{
"oauth2": "https://authentication-dev.censhare.com/auth/realms/censhare/.well-known/openid-configuration",
"webClient": "http://localhost:8082/censhare5/client",
"cihubRestApi": "http://localhost:9000/cihub"
} 

Steps to configure

Simply add this snippet to the application.yml  in the /opt/censer/core-cloud-gateway/ folder:

cg:
	## and other values, removed from the example
	public-url:
		## Note: all following URLS can be either full or just paths
		#web-client: /censhare5/client
		#keycloak-realm: https://xxx.yyy.zzz/auth/realms/censhare
		cihub-api: https://xxx.yyy.zzz/cihub

Main documentation abou the Cloud Gateway can be found here. 

Configure CI HUB client in Keycloak

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:

   1. Click Create to configure it manually using the table belowor

   2. Click Import to configure it using cihub.json, the sample config file. You will only need to add the URLs as described on the last step (below the table). Either enter them manually in the UI after importing the JSON, or add them to JSON first and then use it for complete configuration. 

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.

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. 

Configure CI HUB module in the Admin Client

1. 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 URLs and the correct censhare Web domain, separated by comma. The following CIHUB server URLs are provided for now:

     • live.ci-hub.com

     • stage.ci-hub.com

     • dev.ci-hub.com

        

   • 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 Request logging section, you can configure log entries for API requests. 

   Use only for developing and testing of custom schemas!

   
   

7. Click OK to save your configuration and close the dialog.

8. Update the server configuration.

9. Synchronize remote servers if you have a Master-Remote-Server setup.

10. 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://live.ci-hub.com' \ 
    -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  Set up CI HUB in censhare.

    
    

    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 a BigIP F5 and/or haproxy that handles all requests from and to external services. 

Route forwarding for censhare

In the load balancer, set /cihub/ path to the censhare-Server REST ( http://censhare.your-company.com:9000 ), as also explained in the •Load balancing with HAProxy article. 

Steps to be performed by the end users

Please make sure your users are provided:

• the CIHUB license key 

• the correct base URL for the Censhare system they want to use

As also explained in the CI HUB user guide, end users will need to perform the following steps individually:

• Using the license key, create an account with the third-party provider (CIHUB)

• If they want to use it with Adobe or Microsoft applications, install the corrsponding CIHUB plugin for those applications

• Connect to Censhare from the other application by entering the Censhare base URL

For each user trying to connect to Censhare for the first time, CIHUB will perform a check if there is any existing configuration stored on their side for that frontend URL. If none exists and the license is valid, CIHUB will call the "well-known" API endpoint to create such a configuration. The user will be then authenticated by Censhare's Keycloak and served assets they have access to. 

(Optional) Whitelist Canva‘s URLs

If your users plan to use Canva, you will need to explicitly whitelist the following URLs:

1. https://app-aagcgsdkbdg.canva-apps.com/ – Live/Production

2. https://app-aagppabnsou.canva-apps.com/ – Testing/Development (for UI changes and pre-release validation)