TheArchive/zitadel
1
0
Fork 0
mirror of https://github.com/zitadel/zitadel.git synced 2025-01-06 13:57:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update go api client guide (#7099)

Browse Source 
* docs: update go api client guide

* update branch reference
This commit is contained in:
Livio Spring 2023-12-20 17:56:48 +02:00 committed by GitHub
parent e22689c125
commit f4e73b9b75
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 23 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
docs/docs/examples/call-zitadel-api/go.md
View File

@ -8,6 +8,8 @@ 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).
@ -26,109 +28,36 @@ However, we recommend you read the guide on [how to access ZITADEL API](../../gu
You need to add the SDK into Go Modules by:
```bash
go get github.com/zitadel/zitadel-go/v2
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 for the management api and call its `GetMyOrg` function.
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`).
Make sure to fill the vars `issuer` and `api`.
The issuer and api is the domain of your instance you can find it on the instance detail in the ZITADEL Cloud Customer Portal or in the ZITADEL Console.
:::note
The issuer will require the protocol (`https://` and `http://`) and you will only have to specify a port if they're not default (443 for https and 80 for http). The API will always require a port, but no protocol.
:::
```go
package main
import (
"context"
"flag"
"log"
"github.com/zitadel/oidc/pkg/oidc"
"github.com/zitadel/zitadel-go/v2/pkg/client/management"
"github.com/zitadel/zitadel-go/v2/pkg/client/middleware"
"github.com/zitadel/zitadel-go/v2/pkg/client/zitadel"
pb "github.com/zitadel/zitadel-go/v2/pkg/client/zitadel/management"
)
var (
issuer = flag.String("issuer", "", "issuer of your ZITADEL instance (in the form: https://<instance>.zitadel.cloud or https://<yourdomain>)")
api = flag.String("api", "", "gRPC endpoint of your ZITADEL instance (in the form: <instance>.zitadel.cloud:443 or <yourdomain>:443)")
)
func main() {
flag.Parse()
//create a client for the management api providing:
//- issuer (e.g. https://acme-dtfhdg.zitadel.cloud)
//- api (e.g. acme-dtfhdg.zitadel.cloud:443)
//- scopes (including the ZITADEL project ID),
//- a JWT Profile token source (e.g. path to your key json), if not provided, the file will be read from the path set in env var ZITADEL_KEY_PATH
client, err := management.NewClient(
*issuer,
*api,
[]string{oidc.ScopeOpenID, zitadel.ScopeZitadelAPI()},
)
if err != nil {
log.Fatalln("could not create client", err)
}
defer func() {
err := client.Connection.Close()
if err != nil {
log.Println("could not close grpc connection", err)
}
}()
ctx := context.Background()
//call ZITADEL and print the name and creation date of your organisation
//the call was successful if no error occurred
resp, err := client.GetMyOrg(ctx, &pb.GetMyOrgRequest{})
if err != nil {
log.Fatalln("call failed: ", err)
}
log.Printf("%s was created on: %s", resp.Org.Name, resp.Org.Details.CreationDate.AsTime())
}
```go reference
https://github.com/zitadel/zitadel-go/blob/next/example/client/cli/cli.go
```
#### Key JSON
To provide the key JSON to the SDK, simply set an environment variable `ZITADEL_KEY_PATH` with the path to the JSON as value.
```bash
export ZITADEL_KEY_PATH=/Users/test/servicekey.json
```
For development purposes you should be able to set this in your IDE.
If you're not able to set it via environment variable, you can also pass it with an additional option:
```go
client, err := management.NewClient(
[]string{oidc.ScopeOpenID, zitadel.ScopeZitadelAPI()},
zitadel.WithKeyPath("/Users/test/servicekey.json"),
)
```
### Test client
### Test
After you have configured everything correctly, you can simply start the example by:
```bash
go run main.go
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:
```
2021/04/21 11:27:36 DemoOrg was created on: 2021-04-08 13:36:05.578194 +0000 UTC
2023/12/20 08:48:23 INFO retrieved the organisation orgID=165467338479501569 name=DemoOrg
```
## Completion
@ -143,16 +72,12 @@ If you've run into any other problem, don't hesitate to contact us or raise an i
### Whats next?
Now you can proceed implementing our APIs by adding more calls or trying to overwrite the organization context:
Now you can proceed implementing our APIs by adding more calls or using a different service like the SessionService:
```go
respOverwrite, err := client.GetMyOrg(middleware.SetOrgID(ctx, "74161146763996133"), &pb.GetMyOrgRequest{})
if err != nil {
log.Fatalln("call failed: ", err)
}
log.Printf("%s was created on: %s", respOverwrite.Org.Name, respOverwrite.Org.Details.CreationDate.AsTime())
}
api.SessionService().CreateSession(ctx, &session.CreateSessionRequest{})
```
Checkout more [examples from the SDK](https://github.com/zitadel/zitadel-go/blob/main/example) or refer to our [API Docs](/apis/introduction).
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).
> This guide will be updated soon to show you how to use the SDK for your own API as well.

4
docs/docs/examples/login/go.md
View File

@ -118,7 +118,7 @@ https://github.com/zitadel/zitadel-go/blob/next/example/app/templates/profile.ht
### Start your application
You will need to provide some values for the program to run:
- `domain`: Your ZITADEL instance domain, e.g. https://my-domain.zitadel.cloud
- `domain`: Your ZITADEL instance domain, e.g. my-domain.zitadel.cloud
- `key`: The path to the downloaded key.json
- `clientID`: The clientID provided by ZITADEL
- `redirectURI`: The redirectURI registered at ZITADEL
@ -131,7 +131,7 @@ go run main.go --domain <your domain> --key <key> -- clientID <clientID> --redir
This could look like:
```bash
go run main.go --domain https://my-domain.zitadel.cloud --key XKv2Lqd7YAq13NUZVUWZEWZeruqyzViM --clientID 243861220627644836@example --redirectURI http://localhost:8089/auth/callback
go run main.go --domain my-domain.zitadel.cloud --key XKv2Lqd7YAq13NUZVUWZEWZeruqyzViM --clientID 243861220627644836@example --redirectURI http://localhost:8089/auth/callback
```
If you then visit on http://localhost:8089 you should get the following screen:

2
docs/docs/examples/secure-api/go.md
View File

@ -72,7 +72,7 @@ go run main.go --domain <your domain> --key <path>
This could look like:
```bash
go run main.go --domain https://my-domain.zitadel.cloud --key ./api.json
go run main.go --domain my-domain.zitadel.cloud --key ./api.json
```
After you get a successful log: