From e2fdd3f0771445486e9483c53918c89399f27455 Mon Sep 17 00:00:00 2001
From: Stefan Benz <46600784+stebenz@users.noreply.github.com>
Date: Tue, 31 Jan 2023 20:52:47 +0100
Subject: [PATCH] feat: support client_credentials for service users (#5134)
Request an access_token for service users with OAuth 2.0 Client Credentials Grant. Added functionality to generate and remove a secret on service users.
---
.../users/user-detail/user-detail.module.ts | 2 +
.../machine-secret-dialog.component.html | 50 ++
.../machine-secret-dialog.component.scss | 37 ++
.../machine-secret-dialog.component.spec.ts | 24 +
.../machine-secret-dialog.component.ts | 19 +
.../user-detail/user-detail.component.html | 6 +
.../user-detail/user-detail.component.ts | 33 ++
console/src/app/services/mgmt.service.ts | 16 +
console/src/assets/i18n/de.json | 10 +-
console/src/assets/i18n/en.json | 10 +-
console/src/assets/i18n/fr.json | 10 +-
console/src/assets/i18n/it.json | 10 +-
console/src/assets/i18n/zh.json | 10 +-
docs/docs/apis/openidoauth/endpoints.mdx | 47 ++
docs/docs/apis/openidoauth/grant-types.md | 8 +-
docs/docs/apis/proto/management.md | 70 +++
docs/docs/apis/proto/user.md | 1 +
.../guides/integrate/client-credentials.md | 88 +++
docs/sidebars.js | 1 +
.../img/console_serviceusers_secret.gif | Bin 0 -> 4049061 bytes
go.mod | 2 +-
go.sum | 4 +-
internal/api/grpc/management/user.go | 28 +
internal/api/grpc/user/converter.go | 1 +
internal/api/oidc/client.go | 86 ++-
internal/api/oidc/client_credentials.go | 120 ++++
internal/command/user_machine_model.go | 11 +-
internal/command/user_machine_secret.go | 171 ++++++
internal/command/user_machine_secret_test.go | 543 ++++++++++++++++++
internal/domain/machine_secret.go | 14 +
internal/query/iam_member_test.go | 20 +-
internal/query/org_member_test.go | 24 +-
internal/query/project_grant_member_test.go | 24 +-
internal/query/project_member_test.go | 24 +-
internal/query/projection/user.go | 73 ++-
internal/query/projection/user_test.go | 234 +++++---
internal/query/user.go | 13 +
internal/query/user_grant_test.go | 40 +-
internal/query/user_test.go | 263 +++++----
internal/repository/user/eventstore.go | 6 +-
internal/repository/user/machine_secret.go | 171 ++++++
internal/static/i18n/de.yaml | 14 +-
internal/static/i18n/en.yaml | 10 +
internal/static/i18n/fr.yaml | 10 +
internal/static/i18n/it.yaml | 10 +
internal/static/i18n/zh.yaml | 10 +
proto/zitadel/management.proto | 41 ++
proto/zitadel/user.proto | 5 +
48 files changed, 2113 insertions(+), 311 deletions(-)
create mode 100644 console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.html
create mode 100644 console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.scss
create mode 100644 console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.spec.ts
create mode 100644 console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.ts
create mode 100644 docs/docs/guides/integrate/client-credentials.md
create mode 100644 docs/static/img/console_serviceusers_secret.gif
create mode 100644 internal/api/oidc/client_credentials.go
create mode 100644 internal/command/user_machine_secret.go
create mode 100644 internal/command/user_machine_secret_test.go
create mode 100644 internal/domain/machine_secret.go
create mode 100644 internal/repository/user/machine_secret.go
diff --git a/console/src/app/pages/users/user-detail/user-detail.module.ts b/console/src/app/pages/users/user-detail/user-detail.module.ts
index ee25e75a3..749fb035c 100644
--- a/console/src/app/pages/users/user-detail/user-detail.module.ts
+++ b/console/src/app/pages/users/user-detail/user-detail.module.ts
@@ -55,6 +55,7 @@ import { PasswordComponent } from './password/password.component';
import { PasswordlessComponent } from './user-detail/passwordless/passwordless.component';
import { UserDetailComponent } from './user-detail/user-detail.component';
import { UserMfaComponent } from './user-detail/user-mfa/user-mfa.component';
+import { MachineSecretDialogComponent } from './user-detail/machine-secret-dialog/machine-secret-dialog.component';
import { MetadataModule } from 'src/app/modules/metadata/metadata.module';
import { QRCodeModule } from 'angularx-qrcode';
@@ -75,6 +76,7 @@ import { QRCodeModule } from 'angularx-qrcode';
DialogU2FComponent,
DialogPasswordlessComponent,
AuthFactorDialogComponent,
+ MachineSecretDialogComponent,
],
imports: [
ChangesModule,
diff --git a/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.html b/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.html
new file mode 100644
index 000000000..26cfc4458
--- /dev/null
+++ b/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.html
@@ -0,0 +1,50 @@
+
+ {{ 'USER.SECRETDIALOG.CLIENTSECRET' | translate }}
+
+{{ 'USER.SECRETDIALOG.CLIENTSECRET_DESCRIPTION' | translate }}
+
+
+ ClientId: {{ data.clientId }}
+
+
+
+
+ ClientSecret: {{ data.clientSecret }}
+
+
+
+
+
diff --git a/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.scss b/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.scss
new file mode 100644
index 000000000..92a915704
--- /dev/null
+++ b/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.scss
@@ -0,0 +1,37 @@
+.title {
+ font-size: 1.2rem;
+}
+
+.desc {
+ font-size: 0.9rem;
+}
+
+.full-width {
+ width: 100%;
+}
+
+.action {
+ display: flex;
+ justify-content: flex-end;
+
+ .ok-button {
+ margin-left: 0.5rem;
+ }
+}
+
+.flex {
+ display: flex;
+ align-items: center;
+ border: 1px solid #ffffff20;
+ border-radius: 0.5rem;
+ padding-left: 0.5rem;
+ justify-content: space-between;
+
+ .overflow-auto {
+ overflow: auto;
+
+ .desc {
+ font-size: 14px;
+ }
+ }
+}
diff --git a/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.spec.ts b/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.spec.ts
new file mode 100644
index 000000000..a32950bce
--- /dev/null
+++ b/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.spec.ts
@@ -0,0 +1,24 @@
+import { ComponentFixture, TestBed, waitForAsync } from '@angular/core/testing';
+
+import { MachineSecretDialogComponent } from './machine-secret-dialog.component';
+
+describe('MachineSecretDialogComponent', () => {
+ let component: MachineSecretDialogComponent;
+ let fixture: ComponentFixture;
+
+ beforeEach(waitForAsync(() => {
+ TestBed.configureTestingModule({
+ declarations: [MachineSecretDialogComponent],
+ }).compileComponents();
+ }));
+
+ beforeEach(() => {
+ fixture = TestBed.createComponent(MachineSecretDialogComponent);
+ component = fixture.componentInstance;
+ fixture.detectChanges();
+ });
+
+ it('should create', () => {
+ expect(component).toBeTruthy();
+ });
+});
diff --git a/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.ts b/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.ts
new file mode 100644
index 000000000..dfe1187c6
--- /dev/null
+++ b/console/src/app/pages/users/user-detail/user-detail/machine-secret-dialog/machine-secret-dialog.component.ts
@@ -0,0 +1,19 @@
+import { Component, Inject } from '@angular/core';
+import {
+ MAT_LEGACY_DIALOG_DATA as MAT_DIALOG_DATA,
+ MatLegacyDialogRef as MatDialogRef,
+} from '@angular/material/legacy-dialog';
+
+@Component({
+ selector: 'cnsl-machine-secret-dialog',
+ templateUrl: './machine-secret-dialog.component.html',
+ styleUrls: ['./machine-secret-dialog.component.scss'],
+})
+export class MachineSecretDialogComponent {
+ public copied: string = '';
+ constructor(public dialogRef: MatDialogRef, @Inject(MAT_DIALOG_DATA) public data: any) {}
+
+ public closeDialog(): void {
+ this.dialogRef.close(false);
+ }
+}
diff --git a/console/src/app/pages/users/user-detail/user-detail/user-detail.component.html b/console/src/app/pages/users/user-detail/user-detail/user-detail.component.html
index b36261768..3752bb00f 100644
--- a/console/src/app/pages/users/user-detail/user-detail/user-detail.component.html
+++ b/console/src/app/pages/users/user-detail/user-detail/user-detail.component.html
@@ -10,6 +10,12 @@
[hasActions]="['user.write$', 'user.write:' + user.id] | hasRole | async"
>
+
+
diff --git a/console/src/app/pages/users/user-detail/user-detail/user-detail.component.ts b/console/src/app/pages/users/user-detail/user-detail/user-detail.component.ts
index d402a2c02..0fb8372d8 100644
--- a/console/src/app/pages/users/user-detail/user-detail/user-detail.component.ts
+++ b/console/src/app/pages/users/user-detail/user-detail/user-detail.component.ts
@@ -21,6 +21,7 @@ import { Buffer } from 'buffer';
import { EditDialogComponent, EditDialogType } from '../auth-user-detail/edit-dialog/edit-dialog.component';
import { ResendEmailDialogComponent } from '../auth-user-detail/resend-email-dialog/resend-email-dialog.component';
import { LoginPolicy } from 'src/app/proto/generated/zitadel/policy_pb';
+import { MachineSecretDialogComponent } from './machine-secret-dialog/machine-secret-dialog.component';
const GENERAL: SidenavSetting = { id: 'general', i18nKey: 'USER.SETTINGS.GENERAL' };
const GRANTS: SidenavSetting = { id: 'grants', i18nKey: 'USER.SETTINGS.USERGRANTS' };
@@ -189,6 +190,38 @@ export class UserDetailComponent implements OnInit {
});
}
+ public generateMachineSecret(): void {
+ this.mgmtUserService
+ .generateMachineSecret(this.user.id)
+ .then((resp) => {
+ this.toast.showInfo('USER.TOAST.SECRETGENERATED', true);
+ console.log(resp.clientSecret);
+ this.dialog.open(MachineSecretDialogComponent, {
+ data: {
+ clientId: resp.clientId,
+ clientSecret: resp.clientSecret,
+ },
+ width: '400px',
+ });
+ this.refreshUser();
+ })
+ .catch((error) => {
+ this.toast.showError(error);
+ });
+ }
+
+ public removeMachineSecret(): void {
+ this.mgmtUserService
+ .removeMachineSecret(this.user.id)
+ .then((resp) => {
+ this.toast.showInfo('USER.TOAST.SECRETREMOVED', true);
+ this.refreshUser();
+ })
+ .catch((error) => {
+ this.toast.showError(error);
+ });
+ }
+
public changeState(newState: UserState): void {
if (newState === UserState.USER_STATE_ACTIVE) {
this.mgmtUserService
diff --git a/console/src/app/services/mgmt.service.ts b/console/src/app/services/mgmt.service.ts
index ee3840cac..ec1c792b6 100644
--- a/console/src/app/services/mgmt.service.ts
+++ b/console/src/app/services/mgmt.service.ts
@@ -98,6 +98,8 @@ import {
DeactivateUserResponse,
DeleteActionRequest,
DeleteActionResponse,
+ GenerateMachineSecretRequest,
+ GenerateMachineSecretResponse,
GenerateOrgDomainValidationRequest,
GenerateOrgDomainValidationResponse,
GetActionRequest,
@@ -310,6 +312,8 @@ import {
RemoveIDPFromLoginPolicyResponse,
RemoveMachineKeyRequest,
RemoveMachineKeyResponse,
+ RemoveMachineSecretRequest,
+ RemoveMachineSecretResponse,
RemoveMultiFactorFromLoginPolicyRequest,
RemoveMultiFactorFromLoginPolicyResponse,
RemoveOrgDomainRequest,
@@ -717,6 +721,18 @@ export class ManagementService {
return this.grpcService.mgmt.unlockUser(req, null).then((resp) => resp.toObject());
}
+ public generateMachineSecret(userId: string): Promise {
+ const req = new GenerateMachineSecretRequest();
+ req.setUserId(userId);
+ return this.grpcService.mgmt.generateMachineSecret(req, null).then((resp) => resp.toObject());
+ }
+
+ public removeMachineSecret(userId: string): Promise {
+ const req = new RemoveMachineSecretRequest();
+ req.setUserId(userId);
+ return this.grpcService.mgmt.removeMachineSecret(req, null).then((resp) => resp.toObject());
+ }
+
public getPrivacyPolicy(): Promise {
const req = new GetPrivacyPolicyRequest();
return this.grpcService.mgmt.getPrivacyPolicy(req, null).then((resp) => resp.toObject());
diff --git a/console/src/assets/i18n/de.json b/console/src/assets/i18n/de.json
index 8e914388d..0af5183ba 100644
--- a/console/src/assets/i18n/de.json
+++ b/console/src/assets/i18n/de.json
@@ -240,6 +240,8 @@
"STATE": "Status",
"DELETE": "Benutzer löschen",
"UNLOCK": "Benutzer entsperren",
+ "GENERATESECRET": "Client Secret generieren",
+ "REMOVESECRET": "Client Secret löschen",
"LOCKEDDESCRIPTION": "Dieser Benutzer wurde aufgrund der Überschreitung der maximalen Anmeldeversuche gesperrt und muss zur erneuten Verwendung entsperrt werden.",
"DELETEACCOUNT": "Account löschen",
"DELETEACCOUNT_DESC": "Wenn du diese Aktion ausführst, wirst du abgemeldet und danach keinen Zugriff mehr auf dein Konto haben. Diese Aktion kann nicht rückgängig gemacht werden.",
@@ -265,6 +267,10 @@
"DESCRIPTION": "Klicken Sie den untenstehenden Button um ein Verifizierung-E-Mail an die aktuelle Adresse zu versenden oder ändern Sie die Emailadresse in dem Feld.",
"NEWEMAIL": "Neue Email"
},
+ "SECRETDIALOG": {
+ "CLIENTSECRET": "Client Secret",
+ "CLIENTSECRET_DESCRIPTION": "Verwahre das Client Secret an einem sicheren Ort, da es nicht mehr angezeigt werden kann, sobald der Dialog geschlossen wird."
+ },
"TABLE": {
"DEACTIVATE": "Deaktivieren",
"ACTIVATE": "Aktivieren",
@@ -589,7 +595,9 @@
"MACHINEADDED": "Service User erstellt!",
"DELETED": "Benutzer erfolgreich gelöscht!",
"UNLOCKED": "Benutzer erfolgreich freigeschaltet!",
- "PASSWORDLESSREGISTRATIONSENT": "Link via email versendet."
+ "PASSWORDLESSREGISTRATIONSENT": "Link via email versendet.",
+ "SECRETGENERATED": "Secret erfolgreich generiert!",
+ "SECRETREMOVED": "Secret erfolgreich gelöscht!"
},
"MEMBERSHIPS": {
"TITLE": "ZITADEL Manager-Rollen",
diff --git a/console/src/assets/i18n/en.json b/console/src/assets/i18n/en.json
index 5cc92ce7c..33e80560d 100644
--- a/console/src/assets/i18n/en.json
+++ b/console/src/assets/i18n/en.json
@@ -240,6 +240,8 @@
"STATE": "Status",
"DELETE": "Delete User",
"UNLOCK": "Unlock User",
+ "GENERATESECRET": "Generate Client Secret",
+ "REMOVESECRET": "Remove Client Secret",
"LOCKEDDESCRIPTION": "This user has been locked out due to exceeding the maximum login attempts and must be unlocked to be used again.",
"DELETEACCOUNT": "Delete Account",
"DELETEACCOUNT_DESC": "If you perform this action, you will be logged out and will no longer have access to your account. This action is not reversible, so please continue with caution.",
@@ -265,6 +267,10 @@
"DESCRIPTION": "Click the button below to send a notification to the current email address or change the email address in the field.",
"NEWEMAIL": "New email address"
},
+ "SECRETDIALOG": {
+ "CLIENTSECRET": "Client Secret",
+ "CLIENTSECRET_DESCRIPTION": "Keep your client secret at a safe place as it will disappear once the dialog is closed."
+ },
"TABLE": {
"DEACTIVATE": "Deactivate",
"ACTIVATE": "Activate",
@@ -589,7 +595,9 @@
"MACHINEADDED": "Service User created!",
"DELETED": "User deleted successfully!",
"UNLOCKED": "User unlocked successfully!",
- "PASSWORDLESSREGISTRATIONSENT": "Registration Link sent successfully."
+ "PASSWORDLESSREGISTRATIONSENT": "Registration Link sent successfully.",
+ "SECRETGENERATED": "Secret generated successfully!",
+ "SECRETREMOVED": "Secret removed successfully!"
},
"MEMBERSHIPS": {
"TITLE": "ZITADEL Manager Roles",
diff --git a/console/src/assets/i18n/fr.json b/console/src/assets/i18n/fr.json
index dfddd3fa2..249f4f300 100644
--- a/console/src/assets/i18n/fr.json
+++ b/console/src/assets/i18n/fr.json
@@ -240,6 +240,8 @@
"STATE": "Statut",
"DELETE": "Supprimer l'utilisateur",
"UNLOCK": "Déverrouiller l'utilisateur",
+ "GENERATESECRET": "Générer Client Secret",
+ "REMOVESECRET": "Supprimer Client Secret",
"LOCKEDDESCRIPTION": "Cet utilisateur a été verrouillé pour avoir dépassé le nombre maximum de tentatives de connexion et doit être déverrouillé pour être à nouveau utilisé.",
"DELETEACCOUNT": "Supprimer le compte",
"DELETEACCOUNT_DESC": "Si vous effectuez cette action, vous serez déconnecté et n'aurez plus accès à votre compte. Cette action n'est pas réversible, veuillez donc continuer avec prudence.",
@@ -265,6 +267,10 @@
"DESCRIPTION": "Cliquez sur le bouton ci-dessous pour envoyer une notification à l'adresse e-mail actuelle ou modifier l'adresse e-mail dans le champ.",
"NEWEMAIL": "Nouvelle adresse e-mail"
},
+ "SECRETDIALOG": {
+ "CLIENTSECRET": "Client Secret",
+ "CLIENTSECRET_DESCRIPTION": "Conservez votre secret client dans un endroit sûr car il disparaîtra une fois la boîte de dialogue fermée."
+ },
"TABLE": {
"DEACTIVATE": "Désactiver",
"ACTIVATE": "Activer",
@@ -589,7 +595,9 @@
"MACHINEADDED": "Utilisateur de service créé !",
"DELETED": "Utilisateur supprimé avec succès !",
"UNLOCKED": "Utilisateur déverrouillé avec succès !",
- "PASSWORDLESSREGISTRATIONSENT": "Lien d'enregistrement envoyé avec succès."
+ "PASSWORDLESSREGISTRATIONSENT": "Lien d'enregistrement envoyé avec succès.",
+ "SECRETGENERATED": "Secret généré avec succès !",
+ "SECRETREMOVED": "Secret supprimé avec succès !"
},
"MEMBERSHIPS": {
"TITLE": "Rôles du gestionnaire ZITADEL",
diff --git a/console/src/assets/i18n/it.json b/console/src/assets/i18n/it.json
index a2e1e506c..4f599798b 100644
--- a/console/src/assets/i18n/it.json
+++ b/console/src/assets/i18n/it.json
@@ -240,6 +240,8 @@
"STATE": "Stato",
"DELETE": "Elimina utente",
"UNLOCK": "Sblocca utente",
+ "GENERATESECRET": "Genera Client Secret",
+ "REMOVESECRET": "Elimina Client Secret",
"LOCKEDDESCRIPTION": "Questo utente \u00e8 stato bloccato a causa del superamento dei tentativi massimi di accesso e deve essere sbloccato per essere utilizzato di nuovo.",
"DELETEACCOUNT": "Elimina account personale",
"DELETEACCOUNT_DESC": "Se esegui questa azione, sarai disconnesso e non avrai più accesso al tuo account. Questa azione non può essere invertita.",
@@ -265,6 +267,10 @@
"DESCRIPTION": "Clicca il pulsante qui sotto per inviare una notifica all'indirizzo email corrente o cambiare l'indirizzo email nel campo.",
"NEWEMAIL": "Nuovo indirizzo e-mail"
},
+ "SECRETDIALOG": {
+ "CLIENTSECRET": "Client Secret",
+ "CLIENTSECRET_DESCRIPTION": "Salvate il Client Secret in un luogo sicuro, perch\u00e9 non sarà più disponibile dopo aver chiuso la finestra di dialogo"
+ },
"TABLE": {
"DEACTIVATE": "Disattiva",
"ACTIVATE": "Attiva",
@@ -589,7 +595,9 @@
"MACHINEADDED": "Utente di servizio creato!",
"DELETED": "Utente cancellato con successo!",
"UNLOCKED": "Utente sbloccato con successo!",
- "PASSWORDLESSREGISTRATIONSENT": "Link per la registrazione inviato con successo."
+ "PASSWORDLESSREGISTRATIONSENT": "Link per la registrazione inviato con successo.",
+ "SECRETGENERATED": "Secret generato con successo!",
+ "SECRETREMOVED": "Secret rimosso con successo!"
},
"MEMBERSHIPS": {
"TITLE": "Memberships di ZITADEL",
diff --git a/console/src/assets/i18n/zh.json b/console/src/assets/i18n/zh.json
index c5cc33f56..93ed1bd6d 100644
--- a/console/src/assets/i18n/zh.json
+++ b/console/src/assets/i18n/zh.json
@@ -240,6 +240,8 @@
"STATE": "状态",
"DELETE": "删除用户",
"UNLOCK": "解锁用户",
+ "GENERATESECRET": "生成客户密匙",
+ "REMOVESECRET": "删除客户密匙",
"LOCKEDDESCRIPTION": "此用户因超过最大登录尝试次数而被锁定，必须解锁才能再次使用。",
"DELETEACCOUNT": "删除账户",
"DELETEACCOUNT_DESC": "如果您执行此操作，您将被注销并且无法再访问您的帐户。此操作不可逆，因此请谨慎操作。",
@@ -265,6 +267,10 @@
"DESCRIPTION": "单击下面的按钮可向当前电子邮件地址发送通知或更改电子邮件地址。",
"NEWEMAIL": "新的电子邮件地址"
},
+ "SECRETDIALOG": {
+ "CLIENTSECRET": "客户端秘钥",
+ "CLIENTSECRET_DESCRIPTION": "将您的客户保密在一个安全的地方，因为一旦对话框关闭，便无法再次查看。"
+ },
"TABLE": {
"DEACTIVATE": "停用",
"ACTIVATE": "启用",
@@ -589,7 +595,9 @@
"MACHINEADDED": "服务用户已创建成功!",
"DELETED": "用户删除成功!",
"UNLOCKED": "用户解锁成功!",
- "PASSWORDLESSREGISTRATIONSENT": "注册链接发送成功。"
+ "PASSWORDLESSREGISTRATIONSENT": "注册链接发送成功。",
+ "SECRETGENERATED": "秘密成功生成!",
+ "SECRETREMOVED": "秘密被成功删除!"
},
"MEMBERSHIPS": {
"TITLE": "CITADEL 管理角色",
diff --git a/docs/docs/apis/openidoauth/endpoints.mdx b/docs/docs/apis/openidoauth/endpoints.mdx
index 94a0168ac..aa921d256 100644
--- a/docs/docs/apis/openidoauth/endpoints.mdx
+++ b/docs/docs/apis/openidoauth/endpoints.mdx
@@ -325,6 +325,53 @@ Send a `client_assertion` as JWT for us to validate the signature against the re
| refresh_token | An new opaque refresh_token. |
| token_type | Type of the `access_token`. Value is always `Bearer` |
+### Client Credentials Grant
+
+#### Required request Parameters
+
+| Parameter | Description |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
+| grant_type | Must be `client_credentials` |
+| scope | [Scopes](scopes) you would like to request from ZITADEL. Scopes are space delimited, e.g. `openid profile` |
+
+Additionally, you need to authenticate your client by either sending `client_id` and `client_secret` as Basic Auth Header.
+Check [Client Secret Basic Auth Method](authn-methods#client-secret-basic) on how to build it correctly.
+
+```BASH
+curl --request POST \
+ --url {your_domain}/oauth/v2/token \
+ --header 'Content-Type: application/x-www-form-urlencoded' \
+ --header 'Authorization: Basic ${BASIC_AUTH}' \
+ --data grant_type=client_credentials \
+ --data scope=openid profile
+```
+
+Or you can also send your `client_id` and `client_secret` as parameters in the body:
+
+| Parameter | Description |
+| ------------- | -------------------------------- |
+| client_id | client_id of the application |
+| client_secret | client_secret of the application |
+
+```BASH
+curl --request POST \
+ --url {your_domain}/oauth/v2/token \
+ --header 'Content-Type: application/x-www-form-urlencoded' \
+ --data grant_type=client_credentials \
+ --data client_id=${CLIENT_ID} \
+ --data client_secret=${CLIENT_SECRET} \
+ --data scope=openid profile
+```
+
+#### Successful Client Credentials response {#token-client-credentials-response}
+
+| Property | Description |
+| ------------ | ------------------------------------------------------------------------------------- |
+| access_token | An `access_token` as JWT or opaque token |
+| expires_in | Number of second until the expiration of the `access_token` |
+| scope | Scopes of the `access_token`. These might differ from the provided `scope` parameter. |
+| token_type | Type of the `access_token`. Value is always `Bearer` |
+
### Error response
| error_type | Possible reason |
diff --git a/docs/docs/apis/openidoauth/grant-types.md b/docs/docs/apis/openidoauth/grant-types.md
index dd9d693b5..560aa46aa 100644
--- a/docs/docs/apis/openidoauth/grant-types.md
+++ b/docs/docs/apis/openidoauth/grant-types.md
@@ -8,14 +8,14 @@ For a list of supported or unsupported `Grant Types` please have a look at the t
|:------------------------------------------------------|:--------------------|
| Authorization Code | yes |
| Authorization Code with PKCE | yes |
-| Client Credentials | no |
+| Client Credentials | yes |
| Device Authorization | under consideration |
| Implicit | yes |
| JSON Web Token (JWT) Profile | yes |
| Refresh Token | yes |
| Resource Owner Password Credentials | no |
-| Security Assertion Markup Language (SAML) 2.0 Profile | no |
-| Token Exchange | no |
+| Security Assertion Markup Language (SAML) 2.0 Profile | no |
+| Token Exchange | no |
## Authorization Code
@@ -131,4 +131,4 @@ Find out how to use it on the [token endpoint](endpoints#token_endpoint) or the
> Due to growing security concerns we do not support this grant type. With OAuth 2.1 it looks like this grant will be removed.
-**Link to spec.** [OThe OAuth 2.0 Authorization Framework Section 1.3.3](https://tools.ietf.org/html/rfc6749#section-1.3.3)
\ No newline at end of file
+**Link to spec.** [OThe OAuth 2.0 Authorization Framework Section 1.3.3](https://tools.ietf.org/html/rfc6749#section-1.3.3)
diff --git a/docs/docs/apis/proto/management.md b/docs/docs/apis/proto/management.md
index ae987b1f2..e237cbfb4 100644
--- a/docs/docs/apis/proto/management.md
+++ b/docs/docs/apis/proto/management.md
@@ -581,6 +581,30 @@ Changes a machine user
PUT: /users/{user_id}/machine
+### GenerateMachineSecret
+
+> **rpc** GenerateMachineSecret([GenerateMachineSecretRequest](#generatemachinesecretrequest))
+[GenerateMachineSecretResponse](#generatemachinesecretresponse)
+
+Generates and sets a new machine secret
+
+
+
+ PUT: /users/{user_id}/secret
+
+
+### RemoveMachineSecret
+
+> **rpc** RemoveMachineSecret([RemoveMachineSecretRequest](#removemachinesecretrequest))
+[RemoveMachineSecretResponse](#removemachinesecretresponse)
+
+Removes the machine secret
+
+
+
+ DELETE: /users/{user_id}/secret
+
+
### GetMachineKeyByIDs
> **rpc** GetMachineKeyByIDs([GetMachineKeyByIDsRequest](#getmachinekeybyidsrequest))
@@ -4425,6 +4449,30 @@ This is an empty request
+### GenerateMachineSecretRequest
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| user_id | string | - | string.min_len: 1
|
+
+
+
+
+### GenerateMachineSecretResponse
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| client_id | string | - | |
+| client_secret | string | - | |
+| details | zitadel.v1.ObjectDetails | - | |
+
+
+
+
### GenerateOrgDomainValidationRequest
@@ -7175,6 +7223,28 @@ This is an empty request
+### RemoveMachineSecretRequest
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| user_id | string | - | string.min_len: 1
string.max_len: 200
|
+
+
+
+
+### RemoveMachineSecretResponse
+
+
+
+| Field | Type | Description | Validation |
+| ----- | ---- | ----------- | ----------- |
+| details | zitadel.v1.ObjectDetails | - | |
+
+
+
+
### RemoveMultiFactorFromLoginPolicyRequest
diff --git a/docs/docs/apis/proto/user.md b/docs/docs/apis/proto/user.md
index b3fd8e9bd..b4e15c084 100644
--- a/docs/docs/apis/proto/user.md
+++ b/docs/docs/apis/proto/user.md
@@ -133,6 +133,7 @@ title: zitadel/user.proto
| ----- | ---- | ----------- | ----------- |
| name | string | - | |
| description | string | - | |
+| has_secret | bool | - | |
diff --git a/docs/docs/guides/integrate/client-credentials.md b/docs/docs/guides/integrate/client-credentials.md
new file mode 100644
index 000000000..5f09fb16a
--- /dev/null
+++ b/docs/docs/guides/integrate/client-credentials.md
@@ -0,0 +1,88 @@
+---
+title: Client Credentials with Service Users
+---
+
+This is a guide on how to use Client Credentials with service users in ZITADEL. You can read more about users [here](/concepts/structure/users.md).
+
+In ZITADEL, the Client Credentials grant can be used for this non-interactive authentication as alternative to the [JWT profile authentication](serviceusers).
+
+## Create a Service User with a Secret
+
+1. Navigate to Service Users
+2. Click on **New**
+3. Enter a username and a display name
+4. Click on **Create**
+5. Open **Actions** in the top right corner and click on **Generate Client Secret**
+6. Copy the **ClientID** and **ClientSecret** from the dialog
+
+:::note
+Be sure to copy in particular the ClientSecret. You won't be able to retrieve it again.
+If you lose it, you will have to generate a new one.
+:::
+
+
+
+## Grant role for ZITADEL
+
+To be able to access the ZITADEL APIs your service user needs permissions to ZITADEL.
+
+1. Go to the detail page of your organization
+2. Click in the top right corner the "+" button
+3. Search for your service user
+4. Give the user the role you need, for the example we choose Org Owner (More about [ZITADEL Permissions](../manage/console/managers))
+
+
+
+## Authenticating a service user
+
+In this step we will authenticate a service user and receive an access_token to use against the ZITADEL API.
+
+You will need to craft a POST request to ZITADEL's token endpoint:
+
+```bash
+curl --request POST \
+ --url https://{your_domain}.zitadel.cloud/oauth/v2/token \
+ --header 'Content-Type: application/x-www-form-urlencoded' \
+ --header 'Authorization: Basic ${BASIC_AUTH}' \
+ --data grant_type=client_credentials \
+ --data scope='openid profile email urn:zitadel:iam:org:project:id:zitadel:aud'
+```
+
+* `grant_type` should be set to `client_credentials`
+* `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile`, `email`
+ and `urn:zitadel:iam:org:project:id:zitadel:aud`. The latter provides access to the ZITADEL API.
+
+You should receive a successful response with `access_token`, `token_type` and time to expiry in seconds as `expires_in`.
+
+```bash
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
+ "token_type": "Bearer",
+ "expires_in": 43199
+}
+```
+
+## Call ZITADEL API with Token
+
+Because the received Token includes the `urn:zitadel:iam:org:project:id:zitadel:aud` scope, we can send it in your requests to the ZITADEL API as Authorization Header.
+In this example we read the organization of the service user.
+
+```bash
+curl --request GET \
+ --url {your-domain}/management/v1/orgs/me \
+ --header 'Authorization: Bearer ${TOKEN}'
+```
+
+## Summary
+
+* With service users you can secure machine-to-machine communication
+* Client Credentials provide an alternative way to JWT Profile for service user authentication
+* After successful authorization you can use an access token like for human users
+
+Where to go from here:
+
+* Management API
+* Securing backend API
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 189c86b3e..f769c2546 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -109,6 +109,7 @@ module.exports = {
items: [
"guides/integrate/serviceusers",
"guides/integrate/access-zitadel-apis",
+ "guides/integrate/client-credentials",
"guides/integrate/pat",
"guides/integrate/access-zitadel-system-api",
"guides/integrate/export-and-import",
diff --git a/docs/static/img/console_serviceusers_secret.gif b/docs/static/img/console_serviceusers_secret.gif
new file mode 100644
index 0000000000000000000000000000000000000000..b44c5554a387c5b967d97c50ab7beb649b14ad21
GIT binary patch
literal 4049061
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