From d4d39dbd80b69543b6e045cb819905e0e266fd17 Mon Sep 17 00:00:00 2001 From: Livio Spring Date: Mon, 8 Aug 2022 14:52:59 +0200 Subject: [PATCH] docs: document authentication for system api (#4140) * docs: add authentication for system api * update defaults.yaml --- cmd/defaults.yaml | 5 +- docs/docs/apis/introduction.mdx | 2 + .../guides/integrate/access-zitadel-apis.md | 4 + .../integrate/access-zitadel-system-api.md | 158 ++++++++++++++++++ docs/sidebars.js | 1 + 5 files changed, 168 insertions(+), 2 deletions(-) create mode 100644 docs/docs/guides/integrate/access-zitadel-system-api.md diff --git a/cmd/defaults.yaml b/cmd/defaults.yaml index 4c7872b5e4..ce9fa26d97 100644 --- a/cmd/defaults.yaml +++ b/cmd/defaults.yaml @@ -215,10 +215,11 @@ EncryptionKeys: SystemAPIUsers: # add keys for authentication of the systemAPI here: + # you can specify any name for the user, but they will have to match the `issuer` and `sub` claim in the JWT: # - superuser: - # Path: /path/to/superuser/key.pem + # Path: /path/to/superuser/key.pem # you can provide the key either by reference with the path # - superuser2: - # Path: /path/to/superuser2/key.pem + # KeyData: # or you can directly embed it as base64 encoded value #TODO: remove as soon as possible SystemDefaults: diff --git a/docs/docs/apis/introduction.mdx b/docs/docs/apis/introduction.mdx index ad71667ace..4d1f01903b 100644 --- a/docs/docs/apis/introduction.mdx +++ b/docs/docs/apis/introduction.mdx @@ -137,6 +137,8 @@ Definition: This API is intended to manage the different ZITADEL instances within the system. +Checkout the guide how to [access the ZITADEL System API](/docs/guides/integrate/access-zitadel-system-api). +
diff --git a/docs/docs/guides/integrate/access-zitadel-apis.md b/docs/docs/guides/integrate/access-zitadel-apis.md index 844b1e2c97..abcba8644f 100644 --- a/docs/docs/guides/integrate/access-zitadel-apis.md +++ b/docs/docs/guides/integrate/access-zitadel-apis.md @@ -28,6 +28,10 @@ title: Access ZITADEL APIs +:::note +This guide focuses on the Admin, Auth and Management APIs. To access the ZITADEL System API, please checkout [this guide](./access-zitadel-system-api). +::: + ## ZITADEL Managers ZITADEL Managers are Users who have permission to manage ZITADEL itself. There are some different levels for managers. diff --git a/docs/docs/guides/integrate/access-zitadel-system-api.md b/docs/docs/guides/integrate/access-zitadel-system-api.md new file mode 100644 index 0000000000..d049a2ce09 --- /dev/null +++ b/docs/docs/guides/integrate/access-zitadel-system-api.md @@ -0,0 +1,158 @@ +--- +title: Access ZITADEL System API +--- +:::note +This guide focuses on the ZITADEL System API. To access the other APIs (Admin, Auth, Management), please checkout [this guide](./access-zitadel-apis). +The ZITADEL System API is currently only available for ZITADEL Self-Hosted deployments. +::: + +## System API User + +The System API works superordinate over all instances. Therefore, you need to define a separate users to get access to this API. +You can do so by customizing the [runtime configuration](/docs/guides/manage/self-hosted/configure#runtime-configuration). + +To authenticate the user a self-signed JWT will be created and utilized. + +You can define any id for your user. This guide will assume it's `system-user-1`. + +## Generate an RSA keypair + +Generate an RSA private key with 2048 bit modulus: + +```bash +openssl genrsa -out system-user-1.pem 2048 +``` + +and export a public key from the newly created private key: + +```bash +openssl rsa -in system-user-1.pem -outform PEM -pubout -out system-user-1.pub +``` + +## Runtime Configuration + +Provide the **public** key to the ZITADEL runtime configuration. + +Either with the path to the key: + +```yaml +SystemAPIUsers: + - system-user-1: + Path: /system-user-1.pub +``` + +or with a base64 encoded value of the key: + +```yaml +SystemAPIUsers: + - system-user-1: + KeyData: +``` + +## Generate JWT + +Similar to the OAuth 2.0 JWT Profile, we will create and sign a JWT. For this API, the JWT will not be used to authenticate against ZITADEL Authorization Server, but rather directly to the API itself. + +The JWT payload will need to contain the following claims: + +```json +{ + "iss": "", + "sub": "", + "aud": "", + "exp": , + "iat": +} +``` + +So for your instance running on `custom-domain.com` the claims could look like this: + +```json +{ + "iss": "system-user-1", + "sub": "system-user-1", + "aud": "https://custom-domain.com", + "iat": 1659957184, + "exp": 1659960784 +} +``` + +:::note +If your system is exposed without TLS or on a dedicated port, be sure to provide this in your audience, e.g. http://localhost:8080 +::: + +### ZITADEL Tools + +If you want to manually create a JWT for a test, you can also use our [ZITADEL Tools](https://github.com/zitadel/zitadel-tools). Download the latest release and run: + +```bash +./key2jwt -audience=https://custom-domain.com -key=system-user-1.pem -issuer=system-user-1 +``` + +## Call the System API + +Now that you configured ZITADEL and created a JWT, you can call the System API and authenticate using the token: + +```bash +curl --request POST \ + --url {your_domain}/system/v1/instances/_search \ + --header 'Authorization: Bearer {token}' \ + --header 'Content-Type: application/json' +``` + +You should get a successful response with a `totalResult` number of 1 and the details of your instance: + +```json +{ + "details": { + "totalResult": "1" + }, + "result": [ + { + "id": "172698969497928101", + "details": { + "sequence": "102", + "creationDate": "2022-08-02T09:30:10.781068Z", + "changeDate": "2022-08-02T09:30:10.781068Z", + "resourceOwner": "172698969497928101" + }, + "state": "STATE_RUNNING", + "name": "ZITADEL", + "domains": [ + { + "details": { + "sequence": "108", + "creationDate": "2022-08-02T09:30:10.781068Z", + "changeDate": "2022-08-02T09:30:10.781068Z", + "resourceOwner": "172698969497928101" + }, + "domain": "custom-domain.com", + "primary": true + }, + { + "details": { + "sequence": "108", + "creationDate": "2022-08-02T09:30:10.781068Z", + "changeDate": "2022-08-02T09:30:10.781068Z", + "resourceOwner": "172698969497928101" + }, + "domain": "zitadel-gnft7o.custom-domain.com", + "generated": true + } + ] + } + ] +} +``` + +With this token you are allowed to access the whole [ZITADEL System API](../../apis/proto/system). + +## Summary + +* Create an RSA keypair +* Provide the public key with a userID to ZITADEL using the runtime configuration +* Authorize the request with a JWT signed with your private key + +Where to go from here: + +* [ZITADEL API Documentation](../../apis/introduction) diff --git a/docs/sidebars.js b/docs/sidebars.js index acbbd3516b..d9cd5522f4 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -117,6 +117,7 @@ module.exports = { items: [ "guides/integrate/identity-brokering", "guides/integrate/access-zitadel-apis", + "guides/integrate/access-zitadel-system-api", "guides/integrate/authenticated-mongodb-charts", "guides/integrate/auth0", "guides/integrate/azuread",