Offering a custom partner connector

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

If you have more than 1,000 customers and want to replicate your designs for them to use, follow this guide. If you have fewer customers, use workbook export and object embedding. You can contribute to the Gallery yourself.

Advantages of using a connector for DataLens partners:

• Easy user access to data.
• Data access management: each user only sees the data they have access to.
• Deployment of a ready-made configurable dashboard with your data.

How to become a partnerHow to become a partner

On the Yandex Cloud Marketplace home page, click Offer product and fill in your application.

After that, a DataLens manager will get in contact with you.

You need to provide this product information to the DataLens manager:

• 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 based on the ClickHouse® cluster that will store your users' data.

1. Create a ClickHouse® cluster in the cloud.

   1. In the cluster, add a database user named datalens with readonly = 2.

      Note

      If the user management via SQL is enabled for the cluster, you can create a user with this 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 upon receipt of your request in Marketplace.

3. Generate an RSA-2048 key pair. Provide the public key and the key version to DataLens managers.
   The key generation requirements are public_exponent=65537, key_size=2048. A key version is an integer. It is required for future seamless key rotation.

   Python code to generate a key pair

   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 will create 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 database.

2. Prepare an access token for the user:

   Warning

   Each user must have a separate access token string.

   1. Generate a JSON file with the customer’s database name, e.g., {"db_name":"client_1234383"}.
   2. Encrypt this file 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 <datalens_key_version>:<partner_key_version>:<encrypted_data>:<signature> format, where:
      • datalens_key_version and partner_key_version: Key versions.
      • encrypted_data: Base64-encoded encrypted JSON file (from Step 2.2).
      • signature: Base64-encoded encrypted message signature (from 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 file 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. Provide the access token to the user via your website or any other way.

User guide for a connectorUser guide for a connector

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

2. Navigates to Yandex Cloud Marketplace, purchases a connector, or activates a free product.

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

4. Enters the access token you provided on the connection creation page. This associates the connection with the database whose name is encrypted in the access token.

   Connection example

   

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

ClickHouse® is a registered trademark of ClickHouse, Inc.