Creating and using a connector

If you are a DataLens partner, you can create your own connector (connection type) and add it to DataLens Marketplace or to the connections page. With the help of a connector, users will be able to create datasets, charts, and dashboards from your data.

Advantages of working with a connector for DataLens partners:

• Easy user access to data.
• Data access control (each user only sees the data that you make available).
• Deployment of a ready-made configurable dashboard with your data.

How to become a partner

On the Marketplace home page, click Offer product and complete an application.

After you submit the application, a DataLens manager will contact you.

Provide the DataLens manager with your product information:

• Name in Russian and English.
• Description in Russian and English.
• Use cases in Russian and English.
• User manual in Russian and English.
• Icon (vector, SVG).
• Price and preferred payment method (if your product is fee-based).
• Developer contacts.

Creating a connector

You need to create a connector in the same CH cluster that will host your user data.

1. Create a ClickHouse cluster in the cloud.

   1. In the cluster, add a DB user called datalens with readonly = 2.
   2. In the settings, enable DataLens access and Managing databases via SQL.

2. Pass the password and the cluster host list in to DataLens.

3. Generate a pair of RSA-2048 keys. Pass the public key and the key version in to DataLens.
   Key generation requirements: public_exponent=65537, key_size=2048. A key version is an integer that is required for future seamless key rotation.

   Python code to generate a pair of keys

   from cryptography.hazmat.primitives.asymmetric import rsa
   from cryptography.hazmat.primitives import serialization
   
   private_key = rsa.generate_private_key(
       public_exponent=65537,
       key_size=2048,
   )
   private_pem = private_key.private_bytes(
       encoding=serialization.Encoding.PEM,
       format=serialization.PrivateFormat.TraditionalOpenSSL,
       encryption_algorithm=serialization.NoEncryption()
   ).decode()
   
   public_key = private_key.public_key()
   public_pem = public_key.public_bytes(
       encoding=serialization.Encoding.PEM,
       format=serialization.PublicFormat.SubjectPublicKeyInfo
   ).decode()
   print(public_pem)
   

4. DataLens will also provide you with the public part of its key and the key version.
   At this point, DataLens creates a connector to send queries to your ClickHouse cluster.

Connecting a new user

1. Add databases for your users to the ClickHouse cluster. For every user, create a dedicated database in the ClickHouse cluster. The datalens user's database is granted read access to the database.

2. Prepare an access token for the user:

   Warning

   Each user must have a separate access token string.

   1. Generate a JSON with the client database name, such as {"db_name":"client_1234383"}.

   2. Encrypt the JSON with the DataLens public key. Encryption parameters: padding scheme PKCS1 v1.5.

   3. Sign the encrypted string with your private key. Signature parameters: padding scheme PKCS1 v1.5, signature hash algorithm: SHA1.

   4. Generate an access token using the following structure <datalens_key_version>:<partner_key_version>:<encrypted_data>:<signature>, where:

      • datalens_key_version and partner_key_version are key versions.
      • encrypted_data is the Base64-encoded encrypted JSON (outcome of step 2.2).
      • signature is the Base64-encoded encrypted message signature (outcome of step 2.3).
   Python code to generate the access token

   import json
   from base64 import b64encode, b64decode
   from cryptography.hazmat.primitives import serialization
   from cryptography.hazmat.primitives import hashes
   from cryptography.hazmat.primitives.asymmetric import padding
   
   public_key_datalens_pem = '''-----BEGIN PUBLIC KEY-----...''' # DataLens public RSA key.
   private_key_partner_pem = '''-----BEGIN RSA PRIVATE KEY-----...''' # Your private RSA key. 
   datalens_key_version, partner_key_version = '1', '1' # Key versions.
   
   data = json.dumps({'db_name': 'db_name_123'}) # JSON with the user database in the ClickHouse cluster.
   
   public_key_datalens = serialization.load_pem_public_key(public_key_datalens_pem.encode())
   private_key_partner = serialization.load_pem_private_key(
       private_key_partner_pem.encode(),
       password=None,
   )
   ciphertext = public_key_datalens.encrypt(data.encode(), padding.PKCS1v15()) # Encrypted JSON message with the user database..
   signature = private_key_partner.sign(ciphertext, padding.PKCS1v15(), hashes.SHA1()) # Encrypted message signature. 
   
   access_token = ':'.join((
       datalens_key_version,
       partner_key_version,
       b64encode(ciphertext).decode(encoding='utf-8'),
       b64encode(signature).decode(encoding='utf-8'),
   ))
   

3. Deliver the access token to the user through your website or some other way.

User steps for a connector

1. Gets an access token for DataLens on your website.

2. Goes to DataLens Marketplace, purchases a connector, or activates a free product.

3. Goes to the connections DataLens page and selects an activated connector from the list.

4. Enters the access token you provided on the page where you create new connections. Doing this links the connection to the database whose name is encrypted in the access token.

   Example for connecting

   

5. Saves the connection. At this point, DataLens deploys a standard dashboard based on connector data.

See also

• Marketplace