From f4e73b9b75e16274a81af1e47314d3ddb24574d2 Mon Sep 17 00:00:00 2001 From: Livio Spring Date: Wed, 20 Dec 2023 17:56:48 +0200 Subject: [PATCH] docs: update go api client guide (#7099) * docs: update go api client guide * update branch reference --- docs/docs/examples/call-zitadel-api/go.md | 115 ++++------------------ docs/docs/examples/login/go.md | 4 +- docs/docs/examples/secure-api/go.md | 2 +- 3 files changed, 23 insertions(+), 98 deletions(-) diff --git a/docs/docs/examples/call-zitadel-api/go.md b/docs/docs/examples/call-zitadel-api/go.md index 2ca6a4330f..e9f7654e9a 100644 --- a/docs/docs/examples/call-zitadel-api/go.md +++ b/docs/docs/examples/call-zitadel-api/go.md @@ -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://.zitadel.cloud or https://)") - api = flag.String("api", "", "gRPC endpoint of your ZITADEL instance (in the form: .zitadel.cloud:443 or :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 --key +``` + +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. diff --git a/docs/docs/examples/login/go.md b/docs/docs/examples/login/go.md index b646d6eaa2..02bbd1ebd4 100644 --- a/docs/docs/examples/login/go.md +++ b/docs/docs/examples/login/go.md @@ -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 --key -- 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: diff --git a/docs/docs/examples/secure-api/go.md b/docs/docs/examples/secure-api/go.md index 7ec1cc2e4e..f6a1fd7474 100644 --- a/docs/docs/examples/secure-api/go.md +++ b/docs/docs/examples/secure-api/go.md @@ -72,7 +72,7 @@ go run main.go --domain --key 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: