Creating a partner 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 partnerHow 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.

How to create a connectorHow to create 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.

      Note

      If the user management via SQL is enabled for the cluster, you can create a user with the following command:

      CREATE USER IF NOT EXISTS <username> ON CLUSTER <cluster_name>
          IDENTIFIED WITH plaintext_password by '<user_password>'
          SETTINGS readonly = 2;
      

   2. In the settings, enable Access from DataLens and Database management via SQL.

2. Provide the password and the cluster host list to DataLens managers. They will contact you after they receive your request in Marketplace.

3. Generate a pair of RSA-2048 keys. Provide the public key and the key version to DataLens managers.
   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 userConnecting a new user

1. Add databases intended for your users to the ClickHouse® cluster. Create a dedicated database in the ClickHouse® cluster for each user. The database gets read access from the datalens user's DB.

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 connectorUser 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 DataLens connections page and selects an activated connector from the list.

4. Enters the access token you provided on the page where you create new connections. 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 alsoSee also

• Marketplace

ClickHouse® is a registered trademark of ClickHouse, Inc.