feat: List users by metadata (#10415)

# Which Problems Are Solved

Some users have reported the need of retrieving users given a metadata
key, metadata value or both. This change introduces metadata search
filter on the `ListUsers()` endpoint to allow Zitadel users to search
for user records by metadata.

The changes affect only v2 APIs.

# How the Problems Are Solved

- Add new search filter to `ListUserRequest`: `MetaKey` and `MetaValue`
  - Add SQL indices on metadata key and metadata value
  - Update query to left join `user_metadata` table

# Additional Context

  - Closes #9053 
  - Depends on https://github.com/zitadel/zitadel/pull/10567

---------

Co-authored-by: Silvan <[email protected]>
Co-authored-by: Stefan Benz <[email protected]>
This commit is contained in:
Marco A.
2025-09-01 16:12:36 +00:00
committed by GitHub
co-authored by Silvan Stefan Benz
parent 5517fe234f
commit 8df402fb4f
23 changed files with 1019 additions and 478 deletions
+3 -2
View File
@@ -86,7 +86,7 @@ function enterPassword(page: Response, user: User): Response {
}
check(response, {
'password status ok': (r) => r.status >= 200 && r.status < 300 || fail('enter password failed'),
'password status ok': (r) => (r.status >= 200 && r.status < 300) || fail('enter password failed'),
'password callback': (r) =>
r.url.startsWith(url('/ui/console/auth/callback?code=')) || fail(`wrong password callback: ${r.url}`),
});
@@ -117,7 +117,8 @@ function token(code = '') {
tokenTrend.add(response.timings.duration);
check(response, {
'token status ok': (r) => r.status >= 200 && r.status < 300 || fail(`invalid token response status: ${r.status} body: ${r.body}`),
'token status ok': (r) =>
(r.status >= 200 && r.status < 300) || fail(`invalid token response status: ${r.status} body: ${r.body}`),
});
const token = new Tokens(response.json() as JSONObject);
check(token, {
+2 -1
View File
@@ -19,7 +19,8 @@ export async function addIAMMember(userId: string, roles: string[], accessToken:
},
);
check(res, {
'member added successful': (r) => r.status >= 200 && r.status < 300 || fail(`unable add member: ${JSON.stringify(res)}`),
'member added successful': (r) =>
(r.status >= 200 && r.status < 300) || fail(`unable add member: ${JSON.stringify(res)}`),
});
addIAMMemberTrend.add(res.timings.duration);
}
+4
View File
@@ -0,0 +1,4 @@
export type Metadata = {
key: string;
value: string;
};
+5 -3
View File
@@ -30,7 +30,7 @@ function configuration() {
const res = http.get(url('/.well-known/openid-configuration'));
check(res, {
'openid configuration': (r) => r.status >= 200 && r.status < 300 || fail('unable to load openid configuration'),
'openid configuration': (r) => (r.status >= 200 && r.status < 300) || fail('unable to load openid configuration'),
});
oidcConfig = res.json();
@@ -176,7 +176,8 @@ export async function authRequestByID(id: string, tokens: any): Promise<Response
},
});
check(response, {
'authorize status ok': (r) => r.status >= 200 && r.status < 300 || fail(`auth request by failed: ${JSON.stringify(r)}`),
'authorize status ok': (r) =>
(r.status >= 200 && r.status < 300) || fail(`auth request by failed: ${JSON.stringify(r)}`),
});
authRequestByIDTrend.add(response.timings.duration);
return response;
@@ -202,7 +203,8 @@ export async function finalizeAuthRequest(id: string, session: any, tokens: any)
},
);
check(res, {
'finalize auth request status ok': (r) => r.status >= 200 && r.status < 300 || fail(`finalize auth request failed: ${JSON.stringify(r)}`),
'finalize auth request status ok': (r) =>
(r.status >= 200 && r.status < 300) || fail(`finalize auth request failed: ${JSON.stringify(r)}`),
});
finalizeAuthRequestTrend.add(res.timings.duration);
@@ -0,0 +1,65 @@
import { loginByUsernamePassword } from '../login_ui';
import { createOrg, removeOrg } from '../org';
import { createHuman, User, createMachine, setUserMetadata, listUsers } from '../user';
import { Config } from '../config';
import { check } from 'k6';
import encoding from 'k6/encoding';
const userAmount = parseInt(__ENV.USER_AMOUNT) || 2500;
export async function setup() {
const tokens = loginByUsernamePassword(Config.admin as User);
console.info('setup: admin signed in');
const org = await createOrg(tokens.accessToken!);
console.info(`setup: org (${org.organizationId}) created`);
const users: User[] = [];
await Promise.all(
Array.from({ length: userAmount }, async (_, i) => {
let user: User;
let type: 'human' | 'machine';
if (i % 2 === 0) {
user = await createHuman(`zitizen-${i}`, org, tokens.accessToken!);
type = 'human';
} else {
user = await createMachine(`zitachine-${i}`, org, tokens.accessToken!);
type = 'machine';
}
users.push(user);
await setUserMetadata(
[
{ key: 'type', value: encoding.b64encode(type, 'rawurl') },
{ key: 'org', value: encoding.b64encode(org.organizationId, 'rawurl') },
{ key: 'id', value: encoding.b64encode(user.userId, 'rawurl') },
],
user.userId,
tokens.accessToken!,
);
if (i % 10 === 0) {
console.log(`setup: ${i} of ${userAmount} users setup`);
}
}),
);
console.info(`setup: ${users.length} users created`);
return { tokens, org, users };
}
export default async function (data: any) {
const result = await listUsers(
{
queries: [{ metadataKeyFilter: { key: 'org', method: 'TEXT_FILTER_METHOD_EQUALS' } }],
},
data.tokens.accessToken!,
);
check(result, {
'total result length': (res) => res.details.totalResult == userAmount,
}) || console.log(`unexpected amount of users. expected ${userAmount} but got ${result.details.totalResult}`);
}
export function teardown(data: any) {
removeOrg(data.org, data.tokens.accessToken);
console.info('teardown: org removed');
}
@@ -0,0 +1,67 @@
import { loginByUsernamePassword } from '../login_ui';
import { createOrg, removeOrg } from '../org';
import { createHuman, User, createMachine, setUserMetadata, listUsers } from '../user';
import { Config } from '../config';
import { check } from 'k6';
import encoding from 'k6/encoding';
const userAmount = parseInt(__ENV.USER_AMOUNT) || 2500;
export async function setup() {
const tokens = loginByUsernamePassword(Config.admin as User);
console.info('setup: admin signed in');
const org = await createOrg(tokens.accessToken!);
console.info(`setup: org (${org.organizationId}) created`);
const users: User[] = [];
await Promise.all(
Array.from({ length: userAmount }, async (_, i) => {
let user: User;
let type: 'human' | 'machine';
if (i % 2 === 0) {
user = await createHuman(`zitizen-${i}`, org, tokens.accessToken!);
type = 'human';
} else {
user = await createMachine(`zitachine-${i}`, org, tokens.accessToken!);
type = 'machine';
}
users.push(user);
await setUserMetadata(
[
{ key: 'type', value: encoding.b64encode(type, 'rawurl') },
{ key: 'org', value: encoding.b64encode(org.organizationId, 'rawurl') },
{ key: 'id', value: encoding.b64encode(user.userId, 'rawurl') },
],
user.userId,
tokens.accessToken!,
);
if (i % 10 === 0) {
console.log(`setup: ${i} of ${userAmount} users setup`);
}
}),
);
console.info(`setup: ${users.length} users created`);
return { tokens, org, users };
}
export default async function (data: any) {
const result = await listUsers(
{
queries: [
{ metadataValueFilter: { value: encoding.b64encode('human', 'rawurl'), method: 'BYTE_FILTER_METHOD_EQUALS' } },
],
},
data.tokens.accessToken!,
);
check(result, {
'total result length': (res) => res.details.totalResult == userAmount / 2,
}) || console.log(`unexpected amount of users. expected ${userAmount / 2} but got ${result.details.totalResult}`);
}
export function teardown(data: any) {
removeOrg(data.org, data.tokens.accessToken);
console.info('teardown: org removed');
}
+68
View File
@@ -3,6 +3,7 @@ import { Org } from './org';
import http, { RefinedResponse } from 'k6/http';
import url from './url';
import { check } from 'k6';
import { Metadata } from './metadata';
export type User = {
userId: string;
@@ -298,3 +299,70 @@ export function deleteUser(userId: string, org: Org, accessToken: string): Promi
});
});
}
const setUserMetadataTrend = new Trend('set_user_metadata_duration', true);
export function setUserMetadata(metadata: Metadata[], userId: string, accessToken: string): Promise<RefinedResponse<any>> {
return new Promise((resolve, reject) => {
let response = http.asyncRequest('POST', url(`/v2/users/${userId}/metadata`), JSON.stringify({ metadata: metadata }), {
headers: {
authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
});
response
.then((res) => {
check(res, {
'set user metadata is status ok': (r) => r.status >= 200 && r.status < 300,
}) || console.log(`unable to set user metadata (user id: ${userId}) status: ${res.status} body: ${res.body}`);
setUserMetadataTrend.add(res.timings.duration);
resolve(res);
})
.catch((reason) => {
reject(reason);
});
});
}
export type ListUsersRequest = {
queries: {
metadataKeyFilter?: {
key: string;
method: 'TEXT_FILTER_METHOD_EQUALS' | 'TEXT_FILTER_METHOD_CONTAINS' | 'TEXT_FILTER_METHOD_CONTAINS_IGNORE_CASE';
};
metadataValueFilter?: {
value: string;
method: 'BYTE_FILTER_METHOD_EQUALS' | 'BYTE_FILTER_METHOD_NOT_EQUALS';
};
}[];
};
export type ListUsersResult = {
details: {
totalResult: number;
};
};
const listUsersTrend = new Trend('list_users_duration', true);
export function listUsers(body: ListUsersRequest, accessToken: string): Promise<ListUsersResult> {
return new Promise((resolve, reject) => {
let response = http.asyncRequest('POST', url(`/v2/users`), JSON.stringify(body), {
headers: {
authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
});
response
.then((res) => {
check(res, {
'list users is status ok': (r) => r.status >= 200 && r.status < 300,
}) || console.log(`unable to list users status: ${res.status} body: ${res.body}`);
listUsersTrend.add(res.timings.duration);
resolve(res.json()! as ListUsersResult);
})
.catch((reason) => {
reject(reason);
});
});
}
+46
View File
@@ -0,0 +1,46 @@
import http from 'k6/http';
import { Trend } from 'k6/metrics';
import url from './url';
import { check, fail } from 'k6';
import { Project } from './project';
import { Org } from './org';
export type UserGrant = {
userGrantId: string;
};
const addUserGrantTrend = new Trend('user_grant_add', true);
export async function addUserGrant(
org: Org,
userId: string,
project: Project,
roles: string[],
accessToken: string,
): Promise<UserGrant> {
return new Promise((resolve, reject) => {
let response = http.asyncRequest(
'POST',
url(`/management/v1/users/${userId}/grants`),
JSON.stringify({
projectId: project.id,
roleKeys: roles,
}),
{
headers: {
authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
'x-zitadel-orgid': org.organizationId,
},
},
);
response.then((res) => {
check(res, {
'add User Grant status ok': (r) => r.status >= 200 && r.status < 300,
}) || reject(`unable to add User Grant status: ${res.status} body: ${res.body}`);
addUserGrantTrend.add(res.timings.duration);
resolve(res.json() as UserGrant);
});
});
}