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

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

This webinar, hosted by Altinity CEO Robert Hodges with engineer Andrey Zvonov, explores how ClickHouse® can be made safer for AI workloads by adding OAuth 2.0 and OpenID Connect (OIDC) support. The session begins with a clear explanation of what OAuth and OIDC are, why token-based authentication matters, and the benefits it brings: single sign-on across services, elimination of password sprawl, and centralized access control. Andrey then delivers a hands-on demo showing how Grafana authenticates through Keycloak and forwards tokens to ClickHouse, automatically creating users and assigning roles, all without manually defining those users in ClickHouse itself.

The second part of the talk shifts focus to AI. Robert demonstrates the Altinity MCP server, a new tool written in Go that allows AI agents like Claude to query ClickHouse using OAuth-authenticated sessions. The demo shows Claude browsing the database schema and generating a daily token usage report, all without any hardcoded credentials. The webinar also covers two MCP modes (forward and gating), the technical flow of browser-based OAuth login, the upcoming ClickHouse client login support, and Altinity’s roadmap for extending OAuth to additional tools and connectors. The session closes with a discussion of how Altinity’s open source OAuth implementation differs from the upstream ClickHouse approach.

Key Moments (Timestamps)

Key moments generated with AI assistance.

• 00:08 – Introduction and housekeeping
• 01:03 – About Altinity: cloud, Kubernetes Operator, and enterprise support
• 02:28 – What is OAuth? Level-setting on OAuth 2.0 and OIDC
• 04:11 – Benefits of token-based authentication: SSO, broad adoption, password elimination
• 06:16 – Trade-offs: complexity, setup difficulty, and open source gaps
• 09:09 – Live demo: Grafana, Keycloak, and ClickHouse with token forwarding
• 12:48 – How tokens work: ID token, access token, refresh token
• 16:02 – Configuring ClickHouse: token processor and user directory
• 22:17 – Best practices for access tokens and AI agent access
• 24:17 – AI and the Altinity MCP server: what it is and why it matters
• 26:01 – Live demo: Claude querying ClickHouse via the Altinity MCP server
• 31:10 – How the Altinity MCP server works: forward mode and gating mode
• 35:06 – OAuth roadmap: upcoming features across tools and connectors
• 41:11 – Q&A: Altinity’s open source OAuth vs. the upstream ClickHouse approach

Webinar Transcript

[00:08] – Welcome and Housekeeping

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. I have with me today Andrey Zvonov, who is the person who implemented our support for OAuth, which we’re going to be talking about 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 get a recording sent to your email along with the slides, so you do not have to take frantic notes. We have contact information at the end as well, and we are 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 have run Altinity.Cloud for ClickHouse since 2020 and are deeply experienced in cloud operation of ClickHouse. We are 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 is actually how the company started: 24/7 support for people running business-critical systems, covering everything from “Does this design make sense?” all the way to “My system is down and shedding parts. Please get me back online.” That’s the other part of our business.

We are not the same as ClickHouse, Inc. Our lawyers, and frankly everybody’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 over the years; the total is approaching 1,000 pull requests. We also do a lot of work on ecosystem projects of various kinds, such as the Kubernetes Operator and clickhouse-backup, and so on. That’s all the marketing we’re going to do. Let’s dive in and talk about OAuth.

[02:28] – What Is OAuth? A Level Set

Robert: I’m going to start by assuming that people don’t necessarily have a deep understanding of OAuth, so we’ll do a level set on what’s actually there and then dig into the details with a couple of demos.

When we say “OAuth” in this talk, we are referring to a scheme for accessing ClickHouse using tokens. The way it works is that it actually combines two standards that rest on additional standards below them.

The first is OAuth 2.0, short for Open Authorization 2.0. It is a standard for authorizing access to online services. You’ve seen it in action: for example, when you install a browser extension and it asks, “Are you okay with this app being able to see your calendar?” That’s OAuth authorizing access to features of an online service.

The second standard is OIDC, short for OpenID Connect. This is a standard for authenticating access to online services, in other words, saying who you are. So between the two standards, you have “what you can do” and “who you are.” They overlap in places, which makes them occasionally confusing, but as a whole, they work very well together and they are widely used.

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

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

First, it enables single sign-on. You may have a whole collection of services that you need to access, of which ClickHouse is one. You can control access from a single identity provider, such as Google. This is really important in a large organization. We have customers, for example, who are trading on financial markets and allow their traders direct access to ClickHouse information alongside data from other systems. Being able to control access centrally, define each user, define their rights carefully, and also revoke access or remove users at will is critically important. OAuth enables this.

Second, it is widely supported. The proof of that is what I just described. You see it constantly when using web services, being asked “Are you okay with this?” or “Please sign on to Google to confirm who you are.” It is the prevailing standard for doing this.

Third, it eliminates password management for users, at least up to a point. Traditionally with ClickHouse you might be using LDAP, but typically it’s a login and password. If you have good hygiene, you store them in a password manager, but in practice you end up with credentials scattered across the file system and potentially compromised. OAuth eliminates all of that housekeeping.

[06:16] – Trade-offs and the State of Open Source Support

Robert: Of course, things don’t come for free and there are always trade-offs. One thing you’ll see in this talk is that OAuth is not just one standard but a family of standards that work together. It can be tricky to set up, and diagnosing problems can be difficult.

The second trade-off is that open source ClickHouse doesn’t support it fully. In particular, OIDC, the ability to have native support to connect to an identity provider, get authenticated, and log in, was not available in open source until just a few months ago.

What we have done, and the reason we’re doing this webinar, is that we’ve been working with a number of customers and the Altinity Antalya builds now fully support OIDC plus OAuth 2.0. This is now available, it’s completely open source, and you can go grab the builds and use them without having to talk to us.

Specifically, you’ll want to use an Altinity Antalya version 25.8.16 or higher. It is not currently supported in our Altinity Stable® Builds for ClickHouse®. We’re still deciding when this will land there, because the Altinity Stable Builds put a very high premium on compatibility with upstream ClickHouse and on reliability. Compatibility with upstream is the primary concern. So it’s in the Antalya builds for now, and Antalya also has a bunch of other great features, including all of our data lake support and swarm clusters for separation of storage and compute.

[09:09] – Live Demo: Grafana, Keycloak, and ClickHouse

Andrey: Thank you, Robert. So first of all, I’m going to show a quick 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 showing it.

What I want to demonstrate first is that I have almost no manual configuration in ClickHouse. I have not set up users manually. The only thing I’ve configured is this token authentication flow. Let’s see how it works with Grafana.

When I want to sign in to Grafana, I click “Sign in with Keycloak,” enter my credentials, and go through the login flow, which is something you probably do dozens of times every day with Google. Now let’s connect ClickHouse to Grafana as a data source using the Altinity Grafana Plugin for ClickHouse®. I enter a few details since everything runs in Docker. To use OAuth with ClickHouse, all I have to do is toggle the option called “Forward Identity.” What that does is make Grafana forward the tokens it received from the identity provider all the way to ClickHouse.

Let’s see if it works. And it says: it works. Let’s prove it. The most obvious way is to check the current username.

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 only authentication. What about authorization?

OpenID Connect and this overall flow also support authorization. If you know ClickHouse, you know that if you just create a user without specifying any grants or permissions, it cannot do basically anything. But here you can see that I can list tables and even read data from those tables. I haven’t set up any rights for my user. I just configured a mapping, which I’ll explain in a moment. The user that was implicitly created based on information from the identity provider was also granted some permissions. That was the short demo. Let me now explain what you just saw.

[12:48] – Understanding Tokens: ID Token, Access Token, Refresh Token

Andrey: There are three types of tokens in this flow: the ID token, the access token, and the refresh token. What ClickHouse is working with here is the access token.

The ID token is a token that simply contains user information. The refresh token is a token you use to get a new access token. The access token, sometimes called a bearer token, is the token you present to access a service. Access tokens typically have a very short lifetime, which is why you need a refresh token that lives for a longer period.

In our case, ClickHouse uses the access token to extract user information from the identity provider and to grant roles to the user.

To walk through the flow in more detail, we clicked “Sign in with Keycloak” in Grafana. Grafana went to the identity provider, you authenticated there, and you were redirected back to Grafana with a secret code. This is outsourced authentication. Grafana didn’t check who you are directly. It delegated that to Keycloak and received back a token confirming your identity.

Grafana then holds that token. When you write a query in Grafana, Grafana connects to ClickHouse over HTTP and adds that token as a header to the HTTP request. ClickHouse receives the request, takes the token, and since the token on its own is just a sequence of characters with no inherent meaning, ClickHouse goes back to the identity provider to exchange it for useful information, such as the username. If or when the token has expired, Grafana manages this automatically using the refresh token to get a new access token. You’ll never send ClickHouse a stale token; Grafana handles the substitution.

[16:02] – Configuring ClickHouse: Token Processor and User Directory

Andrey: Let’s talk about how to configure this. There are two key entities. The first is the token processor, which is a component of ClickHouse that knows how to talk to the identity provider. It is a configurable module: it receives a token, exchanges it with the identity provider, and returns useful information such as the username and, optionally, a list of groups the user belongs to. You know these groups from Google, Azure, and so on; they’re basically the same concept.

With the username in hand, ClickHouse has two options: the user exists locally, or it doesn’t.

If the user is defined locally, for example, in users.xml, ClickHouse will try to do authentication only. It checks whether the user is allowed to authenticate using a token, and if so, the process is complete.

The more interesting case is when the user does not exist locally. This is what I showed in the demo. If configured properly, you can use the token and the identity provider as a source of truth about user definitions. You don’t have this user in ClickHouse, but you trust the IDP and the token enough to assume the user may exist. ClickHouse implicitly creates a user with the username extracted from the token.

This is where the groups come in. As I mentioned, a user created this way starts with no rights at all. The groups returned from the identity provider may be mapped to ClickHouse roles. You define a rule for how those groups map onto roles, using a regular expression to transform group names as needed.

The second key entity is the user directory. You can configure ClickHouse to treat information from the token as the authoritative source of user definitions. Looking at the configuration, you define one processor per token-based user directory for communication with the identity provider. You can also define a common role section to grant a role to all users coming from this user directory, even if they don’t belong to any groups in the IDP.

One more useful feature: the session log. You can use it to track which users were created and which users accessed the database, which is exactly what we saw in the MCP demo.

[22:17] – Best Practices for OAuth and AI Agents

Andrey: A few best practices for OAuth, some of which are very generic.

First, keep your access token lifetime short, because if a token is leaked, someone can access services on your behalf. However, if you make it expire every second, that is also a bad decision, because for every query that goes to ClickHouse, ClickHouse will have to communicate with the identity provider, which adds latency.

Second, be especially careful about token access for AI agents. This is a general concern right now, and it warrants careful consideration.

Robert: Great. Thank you, Andrey. Let me take the share back and continue.

[24:17] – AI and the Altinity MCP Server

Robert: I want to talk more directly about AI, since we framed this talk as making ClickHouse safe for AI. To motivate the connection, I’m going to talk about a project we have under active development right now: the Altinity MCP server.

What is an MCP server? It is a very popular way for AI applications to connect to any kind of service. MCP stands for Model Context Protocol. It is a standard that provides agent-readable descriptions of tools and resources that allow connections to things like databases, development tools, GitHub, and so on. There are many MCP servers; if you have an agent, you can probably write one in about 20 minutes.

The Altinity MCP server is written in Go and is currently under development. It has a number of tools, one of which is “execute query,” a mechanism for an AI agent to issue queries to ClickHouse. I could show you diagrams, but I’d rather show you a demo first.

[26:01] – Live Demo: Claude Querying ClickHouse via the Altinity MCP Server

Robert: Let me talk to my favorite agent, who is Claude. I have a connection to this MCP server set up in Altinity.Cloud. It says that it needs authentication, so I’ll let Claude kick off authentication. In this case, we’re doing what’s called browser-based login. The Claude client doesn’t communicate directly with the identity provider because it doesn’t know where it is and doesn’t have the built-in mechanism to talk to it the way Grafana does, since the client is not a web service.

I take the authorization URL, paste it into my browser, and it authenticates. That looked pretty easy, but there’s actually an amazing set of steps that happen to make that authentication work. To make a long story short, the MCP server now has a set of tokens it can use to communicate with ClickHouse. Authentication was successful.

Let’s just ask the database for my login name. I’m kind of paranoid, so I always have Claude tell me exactly what it’s going to do. Here we go. My database login shows my email. That’s basically how it recognizes me. If you check the session log, you’d see my email address. You might say, “It just leaked your email to everyone,” but there’s no problem since it’s all over GitHub via developer certificates of origin anyway.

At this point, I’m logged in with read-only privileges. This MCP server does not allow me to write to the database. Let me ask it: what kind of information is in this database?

It is able to read system tables, so it can figure out what tables exist. It ran SHOW DATABASES, then system.tables, the kinds of things you’d do if you were exploring manually. It has accurately said this looks like Claude API telemetry data. Now let me demonstrate that, through OAuth, I also have the ability to read those tables.

Make me a report of daily token usage.

If you’ve used MCP servers or tools in Claude before, this will look familiar. The key point here is that we didn’t have to worry about providing any credentials. Since it’s all done via OAuth, any tool I use to connect to ClickHouse, as long as it can be configured to handle OAuth, will be in good shape. This will give us a report in a moment.

There we go. We got a nice report showing the day and daily token aggregates, which Claude pulled automatically. These numbers are roughly correct, although I’ll admit getting a number that implied $630 per day was a bit of a shock. It turns out that’s the inferred cost; we’re on a subscription so the actual cost is much less, but we are using AI very actively.

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

Robert: Let me talk a bit about how this was done, because it’s an interesting example of how OAuth wiring works. The Altinity MCP server has a couple of different modes.

Forward mode works similarly to what we saw with Grafana: a session token is passed to the MCP server, and it forwards the tokens it receives to ClickHouse.

More interesting is the gating mode. In this case, we’re not using a token to log into ClickHouse directly. The MCP server handles all authentication and authorization, and then uses a static login and password stored inside the server to actually connect to ClickHouse.

Let me explain the wiring in gating mode, because I was genuinely curious about exactly what happens when you paste that URL into your browser. Here’s what happens in this particular case; it’s pretty similar across most providers.

We’re running Claude and we want to authenticate. Claude calls the MCP server and gets a URL base that it uses to build an authorization URL, which is what we showed on screen. We copy it to the browser (on Linux, the browser doesn’t pop up automatically). The browser first goes to the MCP server, the MCP server forwards it to the identity provider, you sign in, and then it gets forwarded back to the Altinity MCP server. Finally, the Altinity MCP forwards back to the Claude client, which has a port open to receive that last call. That’s how it gets its authorization code back. It’s complicated, but it works and it’s amazingly fast.

In gating mode, once you’re in an active session, you pass your MCP session token along with your query. It goes into the Altinity MCP server, into the tool for running queries, and then the MCP server substitutes in a static login and password. Any communication with the identity provider for validation is handled inside the MCP. Very simple.

These two modes illustrate two different ways ClickHouse can be accessed through OAuth. In gating mode, the MCP server serves as a proxy for login, but once you’re in the database, you have whatever rights are granted to that fixed account.

[35:06] – OAuth Roadmap

Robert: The MCP server is in active development and we’ll have it out in May. Let me talk about our general OAuth roadmap.

Here’s what’s already done, as of Q4 2025: Andrey had Keycloak working, Azure Active Directory (now renamed Microsoft Entra ID) working, and we certified the Altinity Grafana Plugin for ClickHouse®. The plugin itself doesn’t need to know much about OAuth because of the way the forwarding mechanisms work, as we saw.

Here’s what’s on tap:

The ClickHouse client in the next Antalya build, which may be going out right as we speak, will have browser-based login authorization, the same thing we just saw with the MCP server. You’ll be able to use –login and, as long as you have the correct configuration, it will generate a URL, you paste it in, and you authenticate with your IDP.

We’re also adapting our Tableau JDBC connector for token-based authorization with OIDC and OAuth. We will be certifying the ClickHouse Connect Python driver. We’ll be adding UI support in Altinity.Cloud so that configuring OAuth is more of a checkbox experience rather than manually placing configuration files.

Everything we’ve done and shown today is licensed under Apache 2.0. We don’t hold anything back. Our principle is that the building blocks you use for analytics should be openly licensed so you can use them anywhere, with or without a relationship with us. Many of these features have been developed as joint investments with customers. If you have things you’re interested in, we tend to build what people really want. If you see features that are missing, come talk to us.

For more information and examples right now, you can go to the OAuth examples repository on GitHub, which shows all the example code for the setups Andrey demonstrated. Full documentation is coming shortly.

[39:47] – Closing Remarks and Upcoming Webinar

Robert: That’s everything. I’d like to thank you all. We’re here to answer questions.

I’d also like to invite you to our webinar on May 20th, called “AI Toys in the Attic,” where we’ll be sharing features we’ve been building with AI. We use AI very intensively at Altinity, and we’ve been collecting a lot in the background. One place where AI has been incredibly helpful, especially in connection with OAuth, is looking for security holes. Our QA team was one of the first groups in the company to adopt coding agents, and this has turned out to be a very effective way to review code and find gaps. If you’re not doing that, I highly recommend it. Come to the webinar and we’ll talk about what we do there.

The slides and the recording will be coming to your mailbox within the next few hours. Try this stuff out, and we’d love to get your feedback and ideas for making it better.

[41:11] – Q&A: Altinity’s OAuth vs. Upstream ClickHouse

Robert: There is one question here. Andrey, can you talk a little about the difference between what we’ve done and what’s available upstream?

Andrey: Sure. The first thing that comes to mind is that what we’ve done is completely open source. You can look at it, explore it, find bugs, and contribute, including by adding support for an identity provider we don’t support yet, such as GitHub or GitLab.

I can’t be 100% certain about the differences while we’re talking, because I haven’t seen the upstream implementation, since it’s closed-source. But from what is exposed externally, I can say that the upstream implementation is focused on providers that issue JWT tokens. While many providers do issue JWT tokens, not all of them do. For example, Google and GitHub do not issue JWT tokens. From what I understand, the upstream implementation will not work with them.

Robert: Thank you. I think that is one place where the upstream approach diverges from what we’re doing, and whether they converge at some point, we don’t know. In the meantime, let us know what you’d like to see. If you have questions, join our Slack channel or contact us on LinkedIn. I’m Robert Hodges. The slides and recording will be in your mailbox within the next few hours. Thanks again, Andrey. Great having you as a presenter.

Andrey: Thank you for having me. Bye, everybody.

FAQ Section

What is the difference between OAuth 2.0 and OIDC, and how do they work together in ClickHouse? OAuth 2.0 (Open Authorization 2.0) is a standard for authorizing access to online services, defining what a user or application is allowed to do. OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0 that handles authentication, meaning it establishes who the user actually is. In ClickHouse, the two standards work together: OIDC authenticates the user with the identity provider, and the resulting access token carries the information ClickHouse needs to authorize the user’s actions and assign appropriate roles.

Which Altinity builds support OAuth 2.0 and OIDC, and which do not? OAuth 2.0 and OIDC support is currently available in Altinity Antalya builds version 25.8.16 and higher. It is not yet included in the Altinity Stable® Builds for ClickHouse®, because Stable Builds place a high priority on compatibility with upstream ClickHouse and on long-term reliability. When OAuth lands in Stable Builds, it will be announced through the usual release notes.

How does ClickHouse automatically create and authorize users via the identity provider? When a request arrives with a valid token, ClickHouse’s token processor exchanges that token with the identity provider to retrieve the username and optionally a list of groups the user belongs to. If the user doesn’t exist locally in ClickHouse, ClickHouse implicitly creates them. The groups returned by the identity provider are then mapped to ClickHouse roles using configurable rules (including regular expression transforms), so the user is automatically granted the correct permissions without any manual setup.

What is the Altinity MCP server and how does it connect Claude to ClickHouse? The Altinity MCP server is a tool built in Go that implements the Model Context Protocol (MCP), a standard for AI agents to connect to services like databases. It allows AI agents, including Claude, to query ClickHouse by issuing queries through an authenticated session. It supports two modes: forward mode, where the agent’s OAuth token is forwarded directly to ClickHouse, and gating mode, where the MCP server validates the session and substitutes a static ClickHouse account for the actual database connection.

What are the best practices for setting access token lifetimes when using OAuth with ClickHouse? Access tokens should be kept short-lived to minimize the window of exposure if a token is leaked. However, making them expire too quickly, such as every few seconds, creates performance problems because ClickHouse must call the identity provider to validate the token on every query. A practical approach is to set a lifetime measured in minutes rather than seconds, and rely on the client (such as Grafana) to use the refresh token to obtain new access tokens transparently.

How does Altinity’s OAuth implementation differ from the upstream ClickHouse implementation? Altinity’s implementation is fully open source and can be inspected, modified, and extended by the community. The upstream ClickHouse implementation is closed-source. Based on what is publicly observable, the upstream implementation is focused on identity providers that issue JWT tokens, which means it may not work with providers such as Google or GitHub that do not issue JWTs. Altinity’s implementation is designed to work with a broader range of providers.

© 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.