mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-17 10:55:12 +00:00
docs(integrate): improve service user authentication (#7492)
* service users * wip * wip * wip * lower case titles * wip * wip * private key jwt * wip * wip * token introspection * zitadel apis * expiration * replace mermaid with svg * Apply suggestions from code review Co-authored-by: Fabi <[email protected]> * Apply suggestions from code review * boulevard of broken links * my hrefs will go on * docs: add token type to client credential * Update docs/docs/apis/introduction.mdx Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/service-users/authenticate-service-users.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/service-users/authenticate-service-users.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/service-users/authenticate-service-users.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/service-users/private-key-jwt.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/service-users/private-key-jwt.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/service-users/authenticate-service-users.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/service-users/client-credentials.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/service-users/client-credentials.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/_accessing_zitadel_api.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * Update docs/docs/guides/integrate/zitadel-apis/access-zitadel-apis.md Co-authored-by: Florian Forster <[email protected]> * docs: add token type to client credential --------- Co-authored-by: Fabi <[email protected]> Co-authored-by: Fabienne <[email protected]> Co-authored-by: Florian Forster <[email protected]> Co-authored-by: Livio Spring <[email protected]>
This commit is contained in:
co-authored by
Fabi
Florian Forster
Fabienne
Livio Spring
parent
47e5533f0f
commit
376c3a3fff
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Integrate ZITADEL APIs into a Go Application
|
||||
sidebar_label: Example Go
|
||||
---
|
||||
|
||||
This integration guide shows you how to integrate **ZITADEL** into your Go application.
|
||||
It demonstrates how to fetch some data from the ZITADEL management API.
|
||||
|
||||
At the end of the guide you should have an application able to read the details of your organization.
|
||||
|
||||
> This documentation references our [CLI example](https://github.com/zitadel/zitadel-go/blob/next/example/client/cli/cli.go).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The client [SDK](https://github.com/zitadel/zitadel-go) will handle all necessary OAuth 2.0 requests and send the required headers to the ZITADEL API using our [OIDC client library](https://github.com/zitadel/oidc).
|
||||
All that is required, is a service account with an Org Owner (or another role, depending on the needed api requests) role assigned and its key JSON.
|
||||
|
||||
However, we recommend you read the guide on [how to access ZITADEL API](/docs/guides/integrate/zitadel-apis/access-zitadel-apis)) and the associated guides for a basic knowledge of :
|
||||
- [Recommended Authorization Flows](/docs/guides/integrate/login/oidc/oauth-recommended-flows)
|
||||
- [Service Users](/docs/guides/integrate/service-users/authenticate-service-users)
|
||||
|
||||
> Be sure to have a valid key JSON and that its service account is either ORG_OWNER or at least ORG_OWNER_VIEWER before you continue with this guide.
|
||||
|
||||
## Go Setup
|
||||
|
||||
### Add Go SDK to your project
|
||||
|
||||
You need to add the SDK into Go Modules by:
|
||||
|
||||
```bash
|
||||
go get -u github.com/zitadel/zitadel-go/v3
|
||||
```
|
||||
|
||||
### Create example client
|
||||
|
||||
Create a new go file with the content below. This will create a client and call its `GetMyOrg` function on the ManagementService.
|
||||
The SDK will make sure you will have access to the API by retrieving a Bearer Token using JWT Profile with the provided scopes (`openid` and `urn:zitadel:iam:org:project:id:zitadel:aud`).
|
||||
|
||||
```go reference
|
||||
https://github.com/zitadel/zitadel-go/blob/next/example/client/cli/cli.go
|
||||
```
|
||||
|
||||
### Test
|
||||
|
||||
After you have configured everything correctly, you can simply start the example by:
|
||||
|
||||
```bash
|
||||
go run cli.go --domain <your domain> --key <path>
|
||||
```
|
||||
|
||||
This could look like:
|
||||
|
||||
```bash
|
||||
go run cli.go --domain my-domain.zitadel.cloud --key ./api.json
|
||||
```
|
||||
|
||||
This will output something similar to:
|
||||
|
||||
```
|
||||
2023/12/20 08:48:23 INFO retrieved the organisation orgID=165467338479501569 name=DemoOrg
|
||||
```
|
||||
|
||||
## Completion
|
||||
|
||||
You have successfully used the ZITADEL Go SDK to call the management API!
|
||||
|
||||
If you encountered an error (e.g. `code = PermissionDenied desc = No matching permissions found`),
|
||||
ensure your service user has the required permissions by assigning the `ORG_OWNER` or `ORG_OWNER_VIEWER` role
|
||||
and check the mentioned [guides](#prerequisites) at the beginning.
|
||||
|
||||
If you've run into any other problem, don't hesitate to contact us or raise an issue on [ZITADEL](https://github.com/zitadel/zitadel/issues) or in the [SDK](https://github.com/zitadel/zitadel-go/issues).
|
||||
|
||||
### Whats next?
|
||||
|
||||
Now you can proceed implementing our APIs by adding more calls or using a different service like the SessionService:
|
||||
|
||||
```go
|
||||
api.SessionService().CreateSession(ctx, &session.CreateSessionRequest{})
|
||||
```
|
||||
Checkout more [examples from the SDK](https://github.com/zitadel/zitadel-go/blob/next/example),
|
||||
like how you can integrate the [client in your own API](https://github.com/zitadel/zitadel-go/blob/next/example/api/client/main.go)
|
||||
or refer to our [API Docs](/apis/introduction).
|
||||
|
||||
Reference in New Issue
Block a user