Authentication

Gateway Service Accounts & Authentication

Gateway Service Accounts are tightly coupled to the Authentication method you choose to connect your clients to the Gateway.

info

The objective of Authentication, whatever the method used, is to provide Conduktor Gateway with a Service Account name to be used in Kafka, and optionally a set of Groups and a Virtual Cluster to associate to the Service Account.

There are 3 ways to authenticate users with the Gateway:

• Delegating authentication to the backing cluster (Confluent Cloud API Keys for instance)
• Using an External source of authentication such as OAuth/OIDC, mTLS, LDAP
• Using Gateway Local Service Accounts

Each method has its own advantages and limitations, due to the structure of the object returned by the authentication process:

Authentication	Source of Name	Source of Groups	Source of Virtual Cluster
Delegated	✅	🚫	🚫
mTLS	✅	🚫	🚫
External Oauth	✅	✅	✅
Local	✅	✅	✅

Check the dedicated Authentication Configuration page to understand how to configure each method.

tip

Once Authentication is configured, if you don't need Group or Virtual Cluster, then no further step is necessary regarding Service Accounts.

There are a few cases where it's necessary to declare GatewayServiceAccount resources: Local Gateway Users, Service Account mapping or Virtual Cluster mapping.

Local Gateway Users
If you don't use any form of external authentication (delegated, Oauth, mTLS, ...), but still want authentication (you can also stay with unauthenticated users), then you must declare Local Gateway users.

You can generate a tuple user/password using the dedicated endpoint:

POST /admin/username/alice
{
  "lifeTimeSeconds": 7776000
}

Service Account mapping
When you don't have any control on the JWT generated by your OIDC provider, and you need map the sub of the claim to a more friendly and recognizable name in Kafka.

{
  "aud": "https://myapi.example.com",
  "iss": "https://login.microsoftonline.com/{tenant_id}/v2.0",
  "sub": "8d5e86b4-6a41-4e94-b6a8-1e5b7723e858",
  "exp": 1643482800,
  "nbf": 1643479200,
  "iat": 1643479200,
  "nonce": "12345"
}

Given this JWT token, deploying this GatewayServiceAccount resource will map the unreadable sub into a clear name alice, which you will then use for Interceptor Targeting, ACLs, ...

POST /admin/userMappings/v1
{
  "username": "alice",
  "principal": "8d5e86b4-6a41-4e94-b6a8-1e5b7723e858"
}

Virtual Cluster mapping
If you want to use Virtual Cluster feature, deploying this resource will link the service account to the specified Virtual Cluster vc-alice.

POST /admin/userMappings/v1/vcluster/vc-alice
{
  "username": "alice",
  "principal": "8d5e86b4-6a41-4e94-b6a8-1e5b7723e858"
}