Skip to content

Authentication

lht authenticates to Salesforce with OAuth 2.0 and to Snowflake with key-pair (JWT) authentication. It never asks for, or stores, a Salesforce or Snowflake password.

Salesforce

lht supports two server-to-server OAuth flows. Neither needs a browser or a user login.

Flow Best for What lht needs
Client Credentials (default) Most setups; used by lht create-connection --salesforce Consumer key, consumer secret, My Domain
JWT Bearer Unattended jobs where you'd rather manage a certificate than a secret Consumer key, username, private key

Client Credentials flow

  1. In Setup, create an External Client App (or a Connected App) and enable OAuth.
  2. Enable Client Credentials Flow. Add the scopes lht needs: api is enough for sync and reverse ETL.
  3. Set a Run As user. lht acts with that user's permissions, so give it read access to the objects you sync, and write access to the objects you push to.
  4. Copy the Consumer Key and Consumer Secret.
  5. Find your My Domain under Setup → My Domain. It's everything before .my.salesforce.com, for example acme or acme--dev.sandbox.

Salesforce reference: OAuth 2.0 Client Credentials Flow.

Then run:

lht create-connection --salesforce

lht sends the key and secret in a form-encoded POST body to https://<my-domain>.my.salesforce.com/services/oauth2/token, never in the URL.

JWT Bearer flow

  1. Generate a key pair and certificate:
    openssl req -x509 -sha256 -nodes -days 730 -newkey rsa:2048 \
      -keyout sf_private.key -out sf_cert.crt -subj "/CN=lht"
    
  2. In your app, enable Use digital signatures and upload sf_cert.crt.
  3. Pre-authorize the integration user: set the app to "Admin approved users are pre-authorized" and add the user's profile or permission set.
  4. Pass the credentials to lht:
    from lht.user.salesforce_auth import get_salesforce_access_info_from_credentials
    
    access_info = get_salesforce_access_info_from_credentials({
        "auth_flow": "jwt_bearer",
        "client_id": "<consumer key>",
        "username": "integration@example.com",
        "private_key_pem": open("sf_private.key", "rb").read(),
        "sandbox": False,   # True uses https://test.salesforce.com
        # "login_url": "https://acme.my.salesforce.com",   # optional override
    })
    

Snowflake

lht connects through Snowpark using key-pair authentication.

  1. Generate a key pair. Encrypting the private key is optional but recommended:
    openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
    openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
    
  2. Create a role and user, and attach the public key:
    CREATE ROLE IF NOT EXISTS LHT_ROLE;
    GRANT USAGE ON WAREHOUSE COMPUTE_WH TO ROLE LHT_ROLE;
    GRANT USAGE ON DATABASE SALESFORCE TO ROLE LHT_ROLE;
    GRANT USAGE, CREATE TABLE ON SCHEMA SALESFORCE.RAW TO ROLE LHT_ROLE;
    -- optional: allow lht to create schemas it's told to sync into
    GRANT CREATE SCHEMA ON DATABASE SALESFORCE TO ROLE LHT_ROLE;
    
    CREATE USER IF NOT EXISTS LHT_USER DEFAULT_ROLE = LHT_ROLE TYPE = SERVICE;
    GRANT ROLE LHT_ROLE TO USER LHT_USER;
    ALTER USER LHT_USER SET RSA_PUBLIC_KEY = '<contents of rsa_key.pub without the header/footer lines>';
    
  3. Save the connection:
    lht create-connection --snowflake
    
    lht copies the private key into its config directory (see below) with 0600 permissions. It stores the passphrase, if you entered one, in connections.toml, which is also 0600.

Reverse ETL records every ingest job in LOGS.RETL_HISTORY, and --log-results adds the per-record tables, so the role needs CREATE SCHEMA (for LOGS) or ownership of an existing LOGS schema. A role that already owns the schema doesn't need CREATE SCHEMA: lht tries to create the schema, and carries on if it can't. Pass --log-schema (or log_schema= / schema= in Python) to put the tables somewhere else.

Databricks

There is no lht-side Databricks credential, in either place lht can run:

  • On Databricks compute (notebook or Job), the cluster's own identity already holds Unity Catalog access. lht.warehouse.databricks.connect() uses the running Spark session, and the Salesforce credentials come from a secret scope via salesforce_access_info(scope=...).
  • Off-platform (laptop, CI), lht uses Databricks Connect, which reads the ~/.databrickscfg profiles the Databricks CLI writes — set up with databricks auth login. Point the profile at compute with serverless_compute_id = auto or a cluster_id.

Reverse ETL needs write access to the Salesforce objects you're updating, and — for --log-results — CREATE SCHEMA/CREATE TABLE on the catalog holding LOGS. See Databricks.

Where credentials live

lht resolves its config directory in this order:

  1. LHT_HOME env var, if set — used exactly as given, no fallback.
  2. ~/.lakehousetools, if it already exists.
  3. ~/.solomo, if it already exists — the pre-2026-10 default, kept so nothing already relying on it breaks on upgrade.
  4. ~/.lakehousetools — the default for everything new.

Call lht.user.connections.get_lht_home() to see which directory your install is actually using (get_solomo_dir() is the same function, kept for backward compatibility).

Item Location Permissions
Connection settings and secrets <config dir>/connections.toml 0600
Snowflake private keys <config dir>/<key file> 0600
Directory itself <config dir> 0700

Databricks credentials are not among them: those live in ~/.databrickscfg (off-platform) or in the cluster identity and a secret scope (on Databricks).

To avoid a local file entirely (CI, containers, orchestrators, a secret pulled from your own secrets manager at process start), you have two options:

  • Pass credentials straight to create_session() and get_salesforce_access_info_from_credentials() — see Python API.
  • Or call lht.user.connections.register_connection(name, credentials) once, early in your process, then refer to that connection by name everywhere else (create_session(connection_name=...), get_salesforce_access_info(connection_name=...)) exactly as if it were in connections.toml — it never touches the file, and a registered name works even if no connections.toml exists at all. Not persisted; call it again in any new process that needs it.