mirror of
https://github.com/zitadel/zitadel.git
synced 2025-08-11 21:07:31 +00:00
docs: document authentication for system api (#4140)
* docs: add authentication for system api * update defaults.yaml
This commit is contained in:
Livio Spring
@@ -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: <base64 encoded key> # or you can directly embed it as base64 encoded value
|
||||
|
||||
#TODO: remove as soon as possible
|
||||
SystemDefaults:
|
||||
|
||||
@@ -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).
|
||||
|
||||
</div>
|
||||
<div class="apicard-right">
|
||||
|
||||
|
||||
@@ -28,6 +28,10 @@ title: Access ZITADEL APIs
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
:::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.
|
||||
|
||||
158
docs/docs/guides/integrate/access-zitadel-system-api.md
Normal file
158
docs/docs/guides/integrate/access-zitadel-system-api.md
Normal file
@@ -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: <base64 encoded value of system-user-1.pub>
|
||||
```
|
||||
|
||||
## 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": "<userid>",
|
||||
"sub": "<userid>",
|
||||
"aud": "<https://your_domain>",
|
||||
"exp": <now+1h>,
|
||||
"iat": <now>
|
||||
}
|
||||
```
|
||||
|
||||
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)
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user