diff --git a/docs/docs/examples/introduction.mdx b/docs/docs/examples/introduction.mdx index f88ce3afd9..4ee14d51b9 100644 --- a/docs/docs/examples/introduction.mdx +++ b/docs/docs/examples/introduction.mdx @@ -91,9 +91,9 @@ Our examples cover a range of programming languages and frameworks, so no matter golang Go Web - - - SDK + + Guide + SDK @@ -148,9 +148,9 @@ Our examples cover a range of programming languages and frameworks, so no matter golang Golang - + Guide - SDK + SDK diff --git a/docs/docs/examples/login/go.md b/docs/docs/examples/login/go.md new file mode 100644 index 0000000000..b646d6eaa2 --- /dev/null +++ b/docs/docs/examples/login/go.md @@ -0,0 +1,152 @@ +--- +title: ZITADEL with Go +sidebar_label: Go +--- + +This integration guide demonstrates the recommended way to incorporate ZITADEL into your Go web application. +It explains how to enable user login in your application and how to fetch data from the user info endpoint. + +By the end of this guide, your application will have login functionality and will be able to access the current user's profile. + +> This documentation references our [example](https://github.com/zitadel/zitadel-go) on GitHub. +> You can either create your own application or directly run the example by providing the necessary arguments. + +## Set up application + +Before we begin developing our application, we need to perform a few configuration steps in the ZITADEL Console. +You'll need to provide some information about your app. We recommend creating a new app to start from scratch. Navigate to your Project, then add a new application at the top of the page. +Select the **Web** application type and continue. + +![Create app in console](/img/go/app-create.png) + +We recommend that you use [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all applications. + +![Create app in console - set auth method](/img/go/app-create-auth.png) + +### Redirect URIs + +The Redirect URIs field tells ZITADEL where it's allowed to redirect users after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI. +The Post-logout redirect send the users back to a route on your application after they have logged out. + +> If you are following along with the [example](https://github.com/zitadel/zitadel-go), set the dev mode to `true`, the Redirect URIs to and Post redirect URI to . + +![Create app in console - set redirectURI](/img/go/app-create-redirect.png) + +Continue and create the application. + +### Client ID + +After successful creation of the app, a pop-up will appear displaying the app's client ID. Copy the client ID, as you will need it to configure your Go client. + +![Create app in console - copy client_id](/img/go/app-create-clientid.png) + +## Go setup + +Now that you have configured your web application on the ZITADEL side, you can proceed with the integration of your Go client. + +### Install ZITADEL Go SDK + +To connect with ZITADEL, you need to install an OAuth/OIDC client. Run the following command: + +```bash +go get -u github.com/zitadel/zitadel-go/v3 +``` + +### Create the application server + +Create a new go file with the content below. This will create an application with a home and profile page. + +```go reference +https://github.com/zitadel/zitadel-go/blob/next/example/app/app.go +``` + +This will basically set up everything. So let's look at some parts of the code. + +**Register authentication handler**: + +For the authentication to work, the SDK needs some handlers in your application. +In this example we will register them on the `/auth/` prefix. +The SDK itself will then register three routes on that to be able to: + - start the authentication process and redirect to the Login UI (`/auth/login`) + - continue with the authentication process after the login UI (`/auth/callback`) + - terminate the session (`/auth/logout`) + - +```go +router.Handle("/auth/", z.Authentication) +``` + +***Authentication checks*** + +To ensure the user is authenticated before they are able to use your application, the middleware provides two options: +- You can either require the user to be authenticated. If he's not yet, he will be automatically redirected to the Login UI: + ```go + mw.RequireAuthentication()(handler) + ``` +- You can just check if he already is, but still continue serving the page: + ```go + mw.CheckAuthentication()(handler) + ``` + +***Authentication context*** + +If you used either of the authentication checks above, you can then access context information in your handler: +```go +mw.Context(req.Context()) +``` + +### Add pages to your application + +To be able to serve these pages create a `templates` directory in the same folder as you just created the go file. +Now create two HTML files in the new `templates` folder and copy the content of the examples: + +**home.html** + +The home page will display a short welcome message and allow the user to manually start the login process. + +```go reference +https://github.com/zitadel/zitadel-go/blob/next/example/app/templates/home.html +``` + +**profile.html** + +The profile page will display the Userinfo from the authentication context and allow the user to logout. + +```go reference +https://github.com/zitadel/zitadel-go/blob/next/example/app/templates/profile.html +``` + +### 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 +- `key`: The path to the downloaded key.json +- `clientID`: The clientID provided by ZITADEL +- `redirectURI`: The redirectURI registered at ZITADEL +- `port`: The port on which the API will be accessible, default it 8089 + +```bash +go run main.go --domain --key -- clientID --redirectURI +``` + +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 +``` + +If you then visit on http://localhost:8089 you should get the following screen: + +![Home Page](/img/go/app-home.png) + +By clicking on `Login` you will be redirected to your ZITADEL instance. After login with your existing user you will be presented the profile page: + +![Profile Page](/img/go/app-profile.png) + +## Completion + +Congratulations! You have successfully integrated your Go application with ZITADEL! + +If you get stuck, consider checking out our [example](https://github.com/zitadel/zitadel-go) application. +This application includes all the functionalities mentioned in this quickstart. +You can directly start it with your own configuration. If you face issues, contact us or raise an issue on [GitHub](https://github.com/zitadel/zitadel-go/issues). + diff --git a/docs/docs/examples/sdks.md b/docs/docs/examples/sdks.md index 6d58fa5f9a..7ac248b684 100644 --- a/docs/docs/examples/sdks.md +++ b/docs/docs/examples/sdks.md @@ -4,20 +4,21 @@ sidebar_label: SDKs --- On this page you find our official SDKs, links to supporting frameworks and providers, and resources to help with SDKs. -The SDKs wrap either our [gRPC or REST APIs](/docs/apis/introduction) to provide the client with User Authentication and Management for resources. +The SDKs wrap either our [gRPC or REST APIs](/docs/apis/introduction) to provide the client with User Authentication and +Management for resources. ## ZITADEL SDKs -| Language / Framework | Link Github | User Authentication | Manage resources | Notes | -|----------------------|---------------------------------------------------------------| --- | --- | --- | -| .NET | [zitadel-net](https://github.com/smartive/zitadel-net) | ✔️ | ✔️ | `community` | -| Elixir | [zitadel_api](https://github.com/jshmrtn/zitadel_api) | ✔️ | ✔️ | `community` | -| Go | [zitadel-go](https://github.com/zitadel/zitadel-go) | ❌ | ✔️ | `official` | -| JVM | 🚧 [WIP](https://github.com/zitadel/zitadel/discussions/3650) | ❓ | ❓ | TBD | -| Python | 🚧 [WIP](https://github.com/zitadel/zitadel/issues/3675) | ❓ | ❓ | TBD | -| NodeJS | [@zitadel/node](https://www.npmjs.com/package/@zitadel/node) | ❌ | ✔️ | `community` | -| Dart | [zitadel-dart](https://github.com/smartive/zitadel-dart) | ❌ | ✔️ | `community` | -| Rust | [zitadel-rust](https://github.com/smartive/zitadel-rust) | ✔️ | ✔️ | `community` | +| Language / Framework | Link Github | User Authentication | Manage resources | Notes | +|----------------------|---------------------------------------------------------------|-----------------------------------------------------------|------------------|-------------| +| .NET | [zitadel-net](https://github.com/smartive/zitadel-net) | ✔️ | ✔️ | `community` | +| Elixir | [zitadel_api](https://github.com/jshmrtn/zitadel_api) | ✔️ | ✔️ | `community` | +| Go | [zitadel-go](https://github.com/zitadel/zitadel-go) | 🚧 [WIP](https://github.com/zitadel/zitadel-go/tree/next) | ✔️ | `official` | +| JVM | 🚧 [WIP](https://github.com/zitadel/zitadel/discussions/3650) | ❓ | ❓ | TBD | +| Python | 🚧 [WIP](https://github.com/zitadel/zitadel/issues/3675) | ❓ | ❓ | TBD | +| NodeJS | [@zitadel/node](https://www.npmjs.com/package/@zitadel/node) | ❌ | ✔️ | `community` | +| Dart | [zitadel-dart](https://github.com/smartive/zitadel-dart) | ❌ | ✔️ | `community` | +| Rust | [zitadel-rust](https://github.com/smartive/zitadel-rust) | ✔️ | ✔️ | `community` | ## Missing SDK @@ -27,7 +28,8 @@ Is your language/framework missing? Fear not, you can generate your gRPC API Cli 2. Create a `buf.gen.yaml` and configure the [plugins](https://buf.build/plugins) you need 3. Run `buf generate https://github.com/zitadel/zitadel#format=git,tag=v2.23.1` (change the versions to your needs) -Let us make an example with Ruby. Any other supported language by buf will work as well. Consult the [buf plugin registry](https://buf.build/plugins) for more ideas. +Let us make an example with Ruby. Any other supported language by buf will work as well. Consult +the [buf plugin registry](https://buf.build/plugins) for more ideas. ### Example with Ruby @@ -43,7 +45,8 @@ plugins: out: gen ``` -If you now run `buf generate https://github.com/zitadel/zitadel#format=git,tag=v2.23.1` in the folder where your `buf.gen.yaml` is located you should see the folder `gen` appear. +If you now run `buf generate https://github.com/zitadel/zitadel#format=git,tag=v2.23.1` in the folder where +your `buf.gen.yaml` is located you should see the folder `gen` appear. If you run `ls -la gen/zitadel/` you should see something like this: @@ -86,12 +89,14 @@ Import these files into your project to start interacting with ZITADEL's APIs. ## More -While we are not actively maintaining the following projects, it is worth checking out if you're interested in exploring ZITADEL in different programming languages or frameworks. +While we are not actively maintaining the following projects, it is worth checking out if you're interested in exploring +ZITADEL in different programming languages or frameworks. - [NodeJS passport](https://github.com/buehler/node-passport-zitadel) authentication helper - [NextAuth Provider for ZITADEL](https://next-auth.js.org/providers/zitadel) -If we do not provide an example, SDK or guide, we strongly recommend using existing authentication libraries for your language or framework instead of building your own. +If we do not provide an example, SDK or guide, we strongly recommend using existing authentication libraries for your +language or framework instead of building your own. Certified libraries have undergone rigorous testing and validation to ensure high security and reliability. There are many recommended libraries available, this saves time and ensures that users' data is well-protected. diff --git a/docs/sidebars.js b/docs/sidebars.js index aaa282a211..cafcdfc4d6 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -15,6 +15,7 @@ module.exports = { "examples/login/react", "examples/login/flutter", "examples/login/nextjs", + "examples/login/go", ], collapsed: true, }, diff --git a/docs/static/img/go/app-create-auth.png b/docs/static/img/go/app-create-auth.png new file mode 100644 index 0000000000..e54b41bd49 Binary files /dev/null and b/docs/static/img/go/app-create-auth.png differ diff --git a/docs/static/img/go/app-create-clientid.png b/docs/static/img/go/app-create-clientid.png new file mode 100644 index 0000000000..76473e47d6 Binary files /dev/null and b/docs/static/img/go/app-create-clientid.png differ diff --git a/docs/static/img/go/app-create-redirect.png b/docs/static/img/go/app-create-redirect.png new file mode 100644 index 0000000000..e92d2587a6 Binary files /dev/null and b/docs/static/img/go/app-create-redirect.png differ diff --git a/docs/static/img/go/app-create.png b/docs/static/img/go/app-create.png new file mode 100644 index 0000000000..ca78b1ec0c Binary files /dev/null and b/docs/static/img/go/app-create.png differ diff --git a/docs/static/img/go/app-home.png b/docs/static/img/go/app-home.png new file mode 100644 index 0000000000..22e92bbf60 Binary files /dev/null and b/docs/static/img/go/app-home.png differ diff --git a/docs/static/img/go/app-profile.png b/docs/static/img/go/app-profile.png new file mode 100644 index 0000000000..218d1240dc Binary files /dev/null and b/docs/static/img/go/app-profile.png differ