Making ClickHouse® safe for AI: Using OAuth in Altinity Builds

Recorded: April 28 @ 08:00 am PDT
Presenters: Robert Hodges and Andrey Zvonov

In this webinar, Altinity CEO Robert Hodes and engineer Andrey Zvonov walk through how Altinity’s Antalya builds now provide full OAuth 2.0 and OIDC support for ClickHouse® — something that was not available in open-source ClickHouse until very recently. The session covers what OAuth and OIDC are, why token-based authentication matters (especially for AI agents and large enterprises), and how the implementation works end-to-end.

Andrey demonstrates a local setup using Grafana, ClickHouse, and Keycloak — showing how a user can log in via an identity provider (IDP) and have ClickHouse automatically create and authorize the user based on token data, with no manual user configuration inside ClickHouse. Robert then demos the Altinity MCP (Model Context Protocol) server for Claude, showing how AI agents can authenticate securely against ClickHouse using OAuth — without hardcoded credentials.

The webinar also covers OAuth best practices, the Altinity roadmap for expanding OAuth support across drivers and tools, and how Altinity’s approach differs from ClickHouse Inc.’s upstream implementation.

Key Moments (Timestamps)

• 00:00 – Welcome and housekeeping; introduction to the webinar topic
• 01:03 – Introduction to Altinity: who they are, what they build, and how they differ from ClickHouse Inc.
• 02:28 – What is OAuth? Defining OAuth 2.0 and OIDC, and why they are used together
• 04:11 – Benefits of token-based authentication: single sign-on, wide support, and password elimination
• 06:16 – Trade-offs of OAuth: complexity, setup difficulty, and open-source ClickHouse limitations
• 07:02 – Altinity’s solution: OIDC + OAuth 2.0 support in Antalya builds (v25.8.16+)
• 09:19 – Live Demo Part 1: Grafana + Keycloak + ClickHouse OAuth login flow
• 11:18 – Proving OAuth authentication: checking current user and reading data without manual user setup in ClickHouse
• 12:48 – Explaining the three token types: ID token, access token, and refresh token
• 13:48 – Deep dive: how Grafana forwards tokens to ClickHouse and how ClickHouse validates them
• 16:02 – Configuration walkthrough: token processor, user directories, group-to-role mapping, and session logging
• 22:41 – Best practices for OAuth: token lifetime, security hygiene, AI agent access controls
• 24:17 – Live Demo Part 2: The Altinity MCP server for Claude — authenticating an AI agent via OAuth
• 31:10 – How the Altinity MCP server works: Forward Mode vs. Gating Mode
• 35:06 – Altinity OAuth roadmap: ClickHouse client login, Tableau JDBC, Python driver, and cloud UI support
• 37:30 – Open-source philosophy, collaboration opportunities, and how to get involved
• 41:12 – Q&A: Altinity vs. upstream ClickHouse OAuth implementation differences
• 43:14 – Closing: resources, upcoming webinar (May 20th), Slack, and LinkedIn

Transcript

AI helped, human-reviewed, but hey, we’re all fallible…

[00:00] – Welcome, Housekeeping, and Introductions

Robert: Welcome, everybody, to “Making ClickHouse Safer for AI Using OAuth and Altinity Builds.” It’s my pleasure to be here today talking about OAuth. My name is Robert Hodges — I’m CEO of Altinity. With me today is Andrey Zvonov, the engineer who implemented our support for OAuth, which we’re going to be discussing for the next few minutes.

Before we dive in, a couple of housekeeping items, this call is being recorded. If you signed up, you’ll receive a recording and the slides via email, so you don’t need to take frantic notes. We’ll also have contact information at the end, and we’re happy to answer questions throughout.

[01:03] – About Altinity

Robert: In case you haven’t heard of Altinity before, we are a vendor for ClickHouse. We’ve been running a managed cloud for ClickHouse since 2020, and we’re deeply experienced in cloud operations. We’re also the authors of the Altinity Kubernetes Operator for ClickHouse, which many of you on this call are already using.

We also do enterprise support — that’s actually how the company started. 24/7 support for ClickHouse for people running business-critical systems. Everything from “Does this design make sense?” to “My system is down, it’s shedding parts, and it won’t start — please get me back online.” That’s the other side of our business.

One important clarification: we are not the same as ClickHouse Incorporated. Our lawyers — and frankly everyone’s lawyers — like it when I make that clear. We do compete, but because this is open source, we also collaborate in many ways. Altinity has made many contributions directly to ClickHouse — approaching a thousand pull requests. We also do a lot of work in ecosystem projects like the KubernetesOperator and clickhouse-backup.

That’s the marketing fluff. Let’s dive into OAuth.

[02:28] – What Is OAuth? Defining the Standards

Robert: I’m going to start assuming people don’t necessarily have a deep understanding of OAuth, so we’ll do a level-set before digging into the details.

When we say “OAuth,” we’re talking about a scheme for accessing ClickHouse using tokens. It actually combines two standards:

OAuth 2.0 — short for Open Authorization 2.0 — is a standard for authorizing access to online services. You’ve seen it when you install a Chrome extension, and it asks, “Is it okay for this app to access your calendar?” That’s OAuth 2.0 in action — authorizing what a service can do on your behalf.

OIDC — short for OpenID Connect — is a standard for authenticating access to online services. In other words, it’s about proving who you are. So together: OAuth 2.0 handles what you can do, and OIDC handles who you are.

These two standards work together. They overlap in places, which can make them a little confusing, but as a whole the system works well and is very widely used.

[04:11] – Benefits of Token-Based Authentication

Robert: Why do people use token-based authentication and authorization? There are a number of good reasons, and here are three big ones.

1. Single Sign-On. You may have a whole range of services you need to access, of which ClickHouse is one. You can control access from a single identity provider (IDP), such as Google. This is really important in large organizations. We have customers in financial markets, for example, where traders have direct access to ClickHouse data alongside data from other systems. Being able to centrally define each user, control their rights precisely, and revoke or remove them at will is critical. OAuth enables this through Altinity’s OIDC integration.

2. Wide adoption. You see OAuth constantly when using web systems — “Sign in with Google,” “Authorize this app,” and so on. It is the prevailing standard for authorization and authentication online.

3. Password elimination. With ClickHouse, you’re typically using login and password — the most common form of authentication. Even with good hygiene, you end up with credentials scattered across file systems, which are potential sources of compromise. OAuth just eliminates all of that housekeeping.

[06:16] – Trade-offs and the Open-Source Gap

Robert: Of course, nothing comes for free. There are trade-offs.

First, OAuth is not a single standard — it’s a family of overlapping standards. It can be tricky to set up, and diagnosing problems can be difficult.

Second, open-source ClickHouse hasn’t fully supported it, particularly OIDC. The ability to natively connect to an IDP, authenticate, and log in was not available in open-source ClickHouse until a few months ago.

What we’ve done at Altinity — and the reason we’re running this webinar — is that our Altinity Antalya builds now support OIDC plus OAuth 2.0. This is what we’ve been working on with a number of our customers. It’s completely open source, so you don’t need a relationship with us to use it — you can just grab the builds and set it up.

Specifically, you’ll want Altinity Antalya version 25.8.16 or higher. Note that this is not yet supported in our Altinity Stable builds — we’re still evaluating when to include it there, given that stable builds place a very high premium on compatibility with upstream ClickHouse. But Antalya has it today, and all the examples we’re showing are using Antalya.

Antalya also includes our data lake support, Swarm Clusters for storage-compute separation, and other cutting-edge features.

[09:19] – Live Demo Part 1: Grafana + Keycloak + ClickHouse OAuth

Andrey: Thank you, Robert. I’m going to start with a small demo. I have a local setup with a local instance of Grafana, a local instance of ClickHouse, and a local instance of Keycloak.

If you don’t know what Keycloak is, to keep it simple, it’s an identity provider, like Google, but you can run it locally. It’s fully configurable and reproducible, which is why I’m using it for this demo.

One important thing to note: I’ve almost not configured ClickHouse manually at all. I haven’t set up users by hand. The only thing I set up is the token authentication flow. Let me show you how it works with Grafana.

When I want to sign in to Grafana, I click “Sign in with Keycloak,” enter my credentials, and okay, this is the kind of login you probably do dozens of times a day, just through Google instead. Now we haven’t connected ClickHouse yet, so let’s do that. We’ll add ClickHouse as a data source in Grafana using the Altinity plugin for Grafana.

Everything is running in Docker, so the URL is just clickhouse. And all we have to do to make it work with OAuth is toggle the “Forward Identity” option. What that does is make Grafana forward the tokens it received from the identity provider all the way to ClickHouse.

Let’s test it. It says it works. Now let’s prove it. The most obvious way is to check the current username.

Andrey: You can see the current user, and the username is actually the email address of my demo user, which I only set up in Keycloak. I repeat: we have not set up any users in ClickHouse itself.

But that’s just authentication. What about authorization? If you know ClickHouse, you know that if you create a user without specifying any grants or permissions, they basically can’t do anything. But watch — I can list tables, and I can even read data from those tables. I haven’t set up any rights for my user directly. I just configured a group mapping — which I’ll explain in a moment — and the user that was implicitly created based on the token information was also automatically granted the appropriate permissions.

That was the short demo. Now let’s explain what you just saw.

[12:48] – The Three Token Types: ID, Access, and Refresh

Andrey: There are three types of tokens in this flow: the ID token, the access token, and the refresh token.

What ClickHouse actually works with is the access token (sometimes called a bearer token). Here’s the breakdown:

• ID token — contains basic user information.
• Access token — the token you present to services to prove authorization. This is the one ClickHouse uses.
• Refresh token — used to obtain a new access token when the current one expires.

Access tokens typically have a very short lifespan by design. That’s why you need a refresh token, which lives longer. ClickHouse uses the access token to extract user information from the identity provider and to grant the appropriate roles to the user.

[13:48] – How the Full Token Flow Works: Grafana → ClickHouse → IDP

Andrey: Let me walk through what actually happened in that demo in more detail.

When you clicked “Sign in with Keycloak,” Grafana redirected you to the identity provider. You authenticated there and were redirected back to Grafana with a secret code. Grafana outsourced the authentication entirely to Keycloak — it didn’t check your credentials itself. It just received a token confirming who you are.

Now, when you write a query in Grafana — like SELECT currentUser() or reading from a table — Grafana communicates with ClickHouse over HTTP. It attaches the token as an HTTP header on every request.

ClickHouse receives this request. It doesn’t know anything about your Grafana user — it just sees a token, which at face value is just a string of characters. To extract something useful from that token, ClickHouse reaches back out to the identity provider (Keycloak), which returns usable information like the username.

When the access token expires, Grafana handles that automatically using the refresh token — it fetches a new access token and substitutes it into subsequent requests. You will never encounter a failed query due to an expired token because Grafana manages the entire token lifecycle.

[16:02] – Configuration: Token Processor, User Directories, and Role Mapping

Andrey: Now, let’s talk about how to configure this. It’s actually quite simple, but first let me explain the key entities.

Token Processor — this is a component inside ClickHouse that knows how to communicate with your specific identity provider. You configure it once. When ClickHouse receives a token from Grafana (or directly from a user via the ClickHouse client), the token processor exchanges it for meaningful information — most importantly, the username. Optionally, if configured correctly, it will also retrieve the list of groups the user belongs to from the IDP.

User lookup and creation — once ClickHouse has the username from the token, it has two scenarios:

1. The user already exists locally (e.g., defined in users.xml). In this case, ClickHouse only performs authentication — it checks whether this user is allowed to authenticate via token.
2. The user does not exist locally. This is the more interesting case, and the one I demonstrated. If configured to do so, ClickHouse can treat the identity provider as the source of truth for user definitions. It implicitly creates the user based on the username extracted from the token.

Group-to-role mapping — when a user is implicitly created, they initially have no rights. That’s where the groups come in. If groups from the IDP can be mapped to existing ClickHouse roles, those roles are automatically granted to the user.

Looking at the configuration details:

• You define a token processor — one per token-based user directory — which handles communication with the IDP.
• You can define a common role section, which grants a baseline role to all users arriving from a given IDP, regardless of their group membership.
• You can define role transform rules using regular expressions to handle group names from the IDP that contain characters unsupported in ClickHouse role names.
• You can enable session logging to track which users were created, which users logged in, and which users accessed the database.

[22:41] – OAuth Best Practices

Andrey: A few best practices worth highlighting:

Keep access tokens short-lived. If a token is leaked, someone can impersonate you for as long as that token is valid. But don’t make tokens expire every second either — for every query ClickHouse receives, it has to contact the identity provider to validate the token, which adds latency. Find a balance that suits your security and performance requirements.

Be very careful about AI agent access. This is especially important right now. Grant AI agents only the rights they actually need — no more. The principle of least privilege is critical when automated systems are involved.

Those are the key points. With that, I’ll hand it back to Robert.

[24:17] – Live Demo Part 2: Altinity MCP Server + Claude + OAuth

Robert: Thanks, Andrey. Let’s talk more directly about AI, since we billed this as making ClickHouse safe for AI. I want to motivate this with a project we have under active development right now: the Altinity MCP server.

What is an MCP server? MCP stands for Model Context Protocol. It’s a very popular way for AI applications to connect to external services — databases, development tools, GitHub, and so on. It provides LLM-readable descriptions of tools and resources that agents can use. If you have an AI agent, you can probably write a basic MCP server in about 20 minutes.

Our MCP server —Altinity MCP — is written in Go and is currently under active development. It includes a tool called execute_query that allows an agent to issue queries directly to ClickHouse.

Let me show you a demo. Here I am using Claude, with a connection to this MCP server configured in Altinity.cloud. The MCP server says it needs authentication, so I’ll let Claude kick off the authentication process.

In this case, we’re using browser-based login — sometimes called the “device flow.” The Claude client doesn’t communicate directly with the IDP because it doesn’t have built-in web service capabilities the way Grafana does. Instead, it generates a URL for me to paste into my browser. I paste it in, authenticate, and done. That looked easy, but there’s actually a sophisticated series of steps happening behind the scenes to make it work.

The MCP server now has a set of tokens it can use to communicate with ClickHouse. Let me prove it.

Robert: Authentication was successful. Let me ask ClickHouse what my database login name is.

I’m a bit of a micromanager, so I always ask Claude to tell me exactly what it’s going to do before it executes. And there we go — it shows rhodges as my username, identified by my email address. If we looked at the session log, we’d see rhodges@altinity.com.

Now let me show that I have real read access through OAuth. Let me ask what data is in this ClickHouse instance.

Robert: Claude is running SHOW DATABASES and then system.tables — exactly what you’d do manually if you were poking around. It correctly identifies this as Claude API telemetry data.

Now, let me ask for a report.

“Make me a report of daily token usage.”

Robert: As you can see, Claude is connecting to ClickHouse via the MCP server, running the query, and returning aggregated daily data. No credentials were manually provided — this all works because OAuth is handling authentication transparently. Any tool that can be configured to handle OAuth can connect to ClickHouse this way.

We got a nice report. It shows daily aggregates — and I’ll admit I got a bit of a shock when I saw an inferred cost of $630 per day in Claude API usage. It turns out we’re on a subscription, so the actual cost is much lower, but we are using AI very actively at Altinity.

[31:10] – How the Altinity MCP Server Works: Forward Mode vs. Gating Mode

Robert: Let me explain how this was wired together, because it’s another interesting example of how OAuth plumbing works.

The Altinity MCP server has two modes:

Forward Mode — works similarly to what we saw with Grafana. The MCP server has a session token, and it forwards the tokens it receives from the agent out to ClickHouse. ClickHouse handles the token validation itself.

Gating Mode — this is the mode we just demonstrated. In this case, the MCP server handles all authentication and authorization internally, and then communicates with ClickHouse using a static login and password stored inside the MCP server. ClickHouse doesn’t see OAuth tokens at all — the MCP server acts as a proxy for authentication.

Here’s what the browser-based login flow actually looks like step by step:

1. Claude calls the MCP server and receives a base URL for the authorization flow.
2. The MCP server builds a full authorization URL, which is displayed to the user.
3. The user copies and pastes that URL into their browser.
4. The browser is redirected to the MCP server → which forwards to the IDP.
5. The user signs in at the IDP.
6. The IDP redirects back to the Altinity MCP server.
7. The Altinity MCP server redirects the browser back to the Claude client, which has a local port open to receive the final callback and get its code back.

It sounds complicated, but it actually executes in seconds. This is the standard browser-based authorization pattern used across OAuth implementations.

Once authenticated in Gating Mode, every subsequent query from Claude simply includes the MCP session token. The MCP server validates it, substitutes in the static ClickHouse login, and executes the query. ClickHouse just sees a normal authenticated connection.

[35:06] – Altinity OAuth Roadmap

Robert: Let me walk through what’s on our OAuth roadmap. Here’s a summary of what’s already done and what’s coming.

Already completed (as of Q4 2025):

• Keycloak integration
• Azure Active Directory (now Microsoft Entra ID) integration
• Grafana plugin certification — most of the OAuth behavior lives in the Grafana server itself; our plugin just needs to enable forwarding

Coming soon:

• ClickHouse client login via OAuth — the next Antalya build (possibly shipping as of this webinar) will support –login with browser-based OAuth. You’ll be able to run the ClickHouse CLI, trigger the URL flow, and authenticate via your IDP exactly as we just did with the MCP server.
• Tableau JDBC connector — we’re adapting our JDBC connector to support token-based authorization via OIDC and OAuth.
• ClickHouse Connect (Python driver) certification — ensuring the Python driver works correctly with OAuth-authenticated connections.
• Altinity.cloud UI support — right now, you can configure OAuth, but you have to place configuration files manually. We’re adding UI support so it’s more of a checkbox experience.

[37:30] – Open Source, Collaboration, and How to Get Involved

Robert: Everything we’ve shown you today is licensed under Apache 2.0. We don’t hold anything back on ClickHouse. Our principle is that the building blocks you use for analytics should be open and openly licensed, so you can use them anywhere — whether you have a relationship with us or not.

Many of these features have been developed as joint investments with customers. We tend to build things that people actually want and need. If you have a use case where OIDC and OAuth 2.0 could help — and you see features that are missing — please come talk to us. We’re happy to queue something up.

If you’re a developer or want to contribute, check out our OAuth examples project on GitHub, which has all the example code Andrey was working from. Full documentation is coming shortly.

One more thing: AI coding agents like Claude and Codex are actually quite well-informed about how OAuth works — often more so than most humans. They can help you with configuration and troubleshoot problems, especially for well-documented identity providers like Keycloak. Don’t hesitate to use them as a resource.

[41:12] – Q&A: Altinity vs. Upstream ClickHouse OAuth

Robert: There’s a good question about the difference between what we’ve built and what’s available in upstream ClickHouse. Andrey, can you speak to that?

Andrey: Sure. The first thing to note is that what we’ve built is completely open source. You can look at it, explore it, find bugs, and contribute — for example, by adding support for an IDP we don’t yet support, like GitHub or GitLab.

As for the differences from upstream: I can’t be 100% certain because I haven’t seen the upstream implementation — it’s closed source. But from what’s been exposed publicly, the upstream implementation appears to focus only on providers that issue JWT tokens (JSON Web Tokens). While many providers do issue JWT tokens, not all of them do. Google and GitHub, for example, do not issue JWT tokens. From what I understand, the upstream implementation would not work with those providers.

But again, I’m not going to speculate further since I haven’t seen the code directly.

Robert: Right. This is one area where the upstream approach diverges from what we’re doing. Whether they’ll converge at some point, we don’t know. In the meantime, let us know what you’d like to see — we’re delighted to add it.

[43:14] – Closing Remarks and Upcoming Events

Robert: We’re going to wrap up. We’ll hang around for another minute or two if anyone has other questions — or feel free to join our Altinity Slack community or connect with me on LinkedIn (Robert Hodes).

Don’t forget: the slides and recording will be in your inbox within a few hours.

I’d also like to invite you to our next webinar on May 20th — it’s called “AI Toys in the Attic.” We’ve been using AI very intensively at Altinity, collecting things we’ve been building in the background, and we’re now ready to share what we’ve been doing. One area where AI has been particularly valuable is security — our QA team was one of the first groups in the company to adopt coding agents, and it’s been an extremely effective way to review code and find gaps. If you’re not already doing this, I highly recommend it.

Thanks to everyone for attending, and a special thanks to Andrey for an excellent presentation.

Andrey: Thank you for having me. Bye, everyone!

FAQ Section

Q1: What version of Altinity ClickHouse builds do I need to use OAuth? You need Altinity Antalya version 25.8.16 or higher. OAuth 2.0 and OIDC support is not currently available in Altinity Stable builds. Antalya builds are fully open source and available for download without a commercial relationship with Altinity.

Q2: Do I need to manually create users in ClickHouse when using OAuth? No. When configured with a token-based user directory, ClickHouse can implicitly create users based on information extracted from the OAuth access token (such as username and group membership). You do not need to define users in users.xml or manually issue CREATE USER statements. Group-to-role mappings handle authorization automatically.

Q3: Which identity providers does Altinity’s OAuth implementation support? Altinity’s implementation has been tested with Keycloak and Microsoft Entra ID (formerly Azure Active Directory). Because Altinity’s implementation works with providers that do not issue JWT tokens — including Google and GitHub — it is broader than the upstream ClickHouse implementation. Support for additional providers can be contributed via the open-source OAuth examples project.

Q4: How does the Altinity MCP server authenticate AI agents like Claude against ClickHouse? The Altinity MCP server supports two modes. In Forward Mode, it passes the OAuth tokens received from the agent directly to ClickHouse, which validates them with the IDP. In Gating Mode, the MCP server handles all authentication itself and connects to ClickHouse using a static internal credential — acting as an OAuth proxy. Both modes support browser-based login, where the user pastes an authorization URL into a browser to complete authentication.

Q5: How long should access tokens live? Token lifetime is a balance between security and performance. Shorter lifetimes reduce the window of exposure if a token is leaked, but if tokens expire too frequently, ClickHouse must validate with the IDP on every query — adding latency. The right balance depends on your environment, but a typical range is minutes to a few hours. Grafana and similar tools manage token refresh automatically, so users rarely notice expiration.

Q6: How does Altinity’s OAuth support differ from the upstream ClickHouse implementation? Altinity’s implementation is fully open source (Apache 2.0). The upstream ClickHouse Inc. implementation is closed source. From publicly available information, the upstream implementation appears to support only identity providers that issue JWT tokens, which excludes Google and GitHub. Altinity’s implementation supports both JWT and non-JWT providers. The two implementations may diverge further or converge over time.

Copyright Notice: This content is © Altinity, Inc. All rights reserved. Altinity®, Altinity.Cloud®, and Altinity Stable® are registered trademarks of Altinity, Inc. ClickHouse® is a registered trademark of ClickHouse, Inc. Altinity is not affiliated with or associated with ClickHouse, Inc. Kubernetes, MySQL, and PostgreSQL are trademarks and property of their respective owners.