TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2024-12-12 02:54:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: access zitadel apis (#1627)

Browse Source 
* doc: access zitadel apis

* doc: access zitadel apis

* doc: swagger
This commit is contained in:
Fabi 2021-04-20 21:37:30 +02:00 committed by GitHub
parent fdcf728d71
commit c223a9ed61
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 176 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/docs/apis/apis.md
View File

@ -6,6 +6,11 @@ All of our APIs are generated by proto defintions. You can find all the proto de
> More about [Protocol Buffer](https://developers.google.com/protocol-buffers)
## Swagger Documentation
We provide some json files for the swagger documentation of our APIs with the following link: [https://api.zitadel.ch/openapi/v2/swagger/](https://api.zitadel.ch/openapi/v2/swagger/)
The easiest way to have a look at them is, to import them in the [Swagger Editor](https://editor.swagger.io/)
## Authentication API aka Auth
The authentication API (aka Auth API) is used for all operations on the currently logged in user.

2
docs/docs/apis/openidoauth/scopes.md
View File

@ -26,6 +26,6 @@ In addition to the standard compliant scopes we utilize the following scopes.
| urn:zitadel:iam:org:project:role:{rolename} | `urn:zitadel:iam:org:project:role:user` | By using this scope a client can request the claim urn:zitadel:iam:roles:rolename} to be asserted when possible. As an alternative approach you can enable all roles to be asserted from the [project](../../guides/projects) a client belongs to. |
| urn:zitadel:iam:org:domain:primary:{domainname} | `urn:zitadel:iam:org:domain:primary:acme.ch` | When requesting this scope **ZITADEL** will enforce that the user is a member of the selected organization. If the organization does not exist a failure is displayed |
| urn:zitadel:iam:role:{rolename} | | |
| urn:zitadel:iam:org:project:id:{projectid}:aud | ZITADEL's Project id is `urn:zitadel:iam:org:project:id:69234237810729019:aud` | By adding this scope, the requested projectid will be added to the audience of the access and id token |
| `urn:zitadel:iam:org:project:id:{projectid}:aud` | ZITADEL's Project id is `urn:zitadel:iam:org:project:id:69234237810729019:aud` | By adding this scope, the requested projectid will be added to the audience of the access and id token |
> If access to ZITADEL's API's is needed with a service user the scope `urn:zitadel:iam:org:project:id:69234237810729019:aud` needs to be used with the JWT Profile request

132
docs/docs/guides/access-zitadel-apis.md Normal file
View File

@ -0,0 +1,132 @@
---
title: Access ZITADEL APIs
---
<table class="table-wrapper">
<tr>
<td>Description</td>
<td>Learn how to authorize Service Users to access ZITADEL APIs.</td>
</tr>
<tr>
<td>Learning Outcomes</td>
<td>
In this module you will:
<ul>
<li>Grant a Service User for ZITADEL</li>
<li>Authorize a Service User with JWT signed with your private key</li>
</ul>
</td>
</tr>
<tr>
<td>Prerequisites</td>
<td>
<ul>
<li>Knowledge of <a href="/docs/guides/oauth-recommended-flows">Recommended Authorization Flows</a></li>
<li>Knowledge of <a href="/docs/guides/serviceusers">Service Users</a></li>
</ul>
</td>
</tr>
</table>
## ZITADEL Managers
ZITADEL Managers are Users who have permission to manage ZITADEL itself. There are some different levels for managers.
- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole IAM.
- **Org Managers**: Managers in the Organisation Level are able to manage everything within the granted Organisation.
- **Project Mangers**: In this level the user is able to manage a project.
- **Project Grant Manager**: The project grant manager is for projects, which are granted of another organisation.
On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../manuals/admin-managers)
## Exercise: Add ORG_OWNER to Service User
Make sure you have a Service User with a Key. (For more detailed informations about creating a service user go to [Service User](serviceusers))
1. Navigate to Organisation Detail
2. Click the **+** button in the right part of console, in the managers part of details
3. Search the user and select it
4. Choose the role ORG_OWNER
![Add Org Manager](/img/console_org_manager_add.gif)
## Authenticating a service user
In ZITADEL we use the `private_jwt` (**“JWT bearer token with private key”**, [RFC7523](https://tools.ietf.org/html/rfc7523)) authorization grant for this non-interactive authentication.
This is already described in the [Service User](serviceusers), so make sure you follow this guide.
### Request an OAuth token, with audience for ZITADEL
With the encoded JWT from the prior step, you will need to craft a POST request to ZITADEL's token endpoint:
To access the ZITADEL APIs you need the ZITADEL Project ID in the audience of your token.
This is possible by sending a custom scope for the audience. More about [Custom Scopes](../apis/openidoauth/scopes)
Use the scope `urn:zitadel:iam:org:project:id:{projectid}:aud` to include the project id in your audience
> The scope for zitadel.ch is: `urn:zitadel:iam:org:project:id:69234237810729019:aud`
```bash
curl --request POST \
--url https://api.zitadel.ch/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
--data scope='openid profile email urn:zitadel:iam:org:project:id:69234237810729019:aud' \
--data assertion=eyJ0eXAiOiJKV1QiL...
```
* `grant_type` must be set to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
* `scope` should contain any [Scopes](../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email`
* `assertion` is the encoded value of the JWT that was signed with your private key from the prior step
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
}
```
With this token you are allowed to access the [ZITADEL APIs](../apis/introduction) .
## Knowledge Check
* Managers are used for all users to get authorizations for all projects?
- [ ] yes
- [ ] no
* You need the ZITADEL Project Id in your audience and can access this with a custom scope?
- [ ] yes
- [ ] no
<details>
<summary>
Solutions
</summary>
* Managers are used for all users to get authorizations for all projects?
- [ ] yes
- [x] no (Managers are only used to grant users for ZITADEL)
* You need the ZITADEL Project Id in your audience and can access this with a custom scope?
- [x] yes
- [ ] no
</details>
## Summary
* Grant a user for ZITADEL
* Because there is no interactive logon, you need to use a JWT signed with your private key to authorize the user
* With a custom scope (`urn:zitadel:iam:org:project:id:{projectid}:aud`) you can access ZITADEL APIs
Where to go from here:
* [ZITADEL API Documentation](../apis/introduction)

2
docs/docs/guides/serviceusers.md
View File

@ -146,7 +146,7 @@ Content-Type: application/json
}
```
### 4. Verify that you have a valid access toaken
### 4. Verify that you have a valid access token
For this example let's call the userinfo endpoint to verfiy that our access token works.

31
docs/docs/manuals/admin-managers.md Normal file
View File

@ -0,0 +1,31 @@
---
title: ZITADEL Managers
---
ZITADEL Managers are Users who have permission to manage ZITADEL itself. There are some different levels for managers.
- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole IAM.
- **Org Managers**: Managers in the Organisation Level are able to manage everything within the granted Organisation.
- **Project Mangers**: In this level the user is able to manage a project.
- **Project Grant Manager**: The project grant manager is for projects, which are granted of another organisation.
To configure managers in ZITADEL go to the resource where you like to add it (e.g IAM, Organisation, Project, GrantedProject).
In the right part of the console you can finde **MANAGERS** in the details part. Here you have a list of the current managers and can add a new one.
## Roles
| Role | Description |
|---|---|
| IAM_OWNER | Manage the IAM, manage all organisations with their content |
| IAM_OWNER_VIEWER | View the IAM and view all organisations with their content |
| ORG_OWNER | Manage everything within an organisation |
| ORG_OWNER_VIEWER | View everything within an organisation |
| ORG_USER_PERMISSION_EDITOR | Manage user grants and view everything needed for this |
| ORG_PROJECT_PERMISSION_EDITOR | Grant Projects to other organisations and view everything needed for this |
| ORG_PROJECT_CREATOR | This role is used for users in the global organisation. They are allowed to create projects and manage them. |
| PROJECT_OWNER | Manage everything within a project. This includes to grant users for the project. |
| PROJECT_OWNER_VIEWER | View everything within a project.|
| PROJECT_OWNER_GLOBAL | Same as PROJECT_OWNER, but in the global organisation. |
| PROJECT_OWNER_VIEWER_GLOBAL | Same as PROJECT_OWNER_VIEWER, but in the global organisation. |
| PROJECT_GRANT_OWNER | Same as PROJECT_OWNER but for a granted proejct. |

7
docs/sidebars.js
View File

@ -6,6 +6,11 @@ module.exports = {
label: 'User',
items: ['manuals/user'],
},
{
type: 'category',
label: 'Administrator',
items: ['manuals/admin-managers'],
},
],
quickstarts: [
'quickstarts/introduction',
@ -25,7 +30,7 @@ module.exports = {
{
type: 'category',
label: 'Get to know ZITADEL',
items: ['guides/get-started', 'guides/organizations', 'guides/projects', 'guides/serviceusers', 'guides/oauth-recommended-flows', 'guides/identity-brokering'],
items: ['guides/get-started', 'guides/organizations', 'guides/projects', 'guides/oauth-recommended-flows', 'guides/serviceusers', 'guides/access-zitadel-apis', 'guides/identity-brokering'],
},
],
apis: [

BIN
docs/static/img/console_org_manager_add.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.3 MiB