diff --git a/docs/docs/examples/login/vue.md b/docs/docs/examples/login/vue.md new file mode 100644 index 0000000000..082bc9424a --- /dev/null +++ b/docs/docs/examples/login/vue.md @@ -0,0 +1,129 @@ +--- +title: ZITADEL with Vue +sidebar_label: Vue +--- + +This integration guide demonstrates the recommended way to incorporate ZITADEL into your Vue 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. + +:::tip +This documentation references our [example](https://github.com/zitadel/zitadel-vue) on GitHub. +It also uses the @zitadel/vue package with its default configuration. +::: + +## Set up application and obtain keys + +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 **User Agent** application type and continue. +We recommend that you use [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all single page applications. + +![Create app in console](/img/vue/app-create.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 sends your users back to a public route on your application after they have logged out. + +:::tip +If you are following along with the [example](https://github.com/zitadel/zitadel-vue), set the dev mode switch to `true`. +Configure a redirect URIs to *http://localhost:5173/auth/signinwin/zitadel* and a post redirect URI to *http://localhost:5173/*. +::: + +Continue and create the application. + +### Refresh Token and Client ID + +After successful creation of the app, make sure you tick the checkbox to enable refresh tokens. +Also copy the client ID, as you will need it to configure your Vue client. + +![Tick refresh token checkbox](/img/vue/tick-refresh-token.png) + +## Create a project role "admin" and assign it to your user + +Also note the projects resource ID, as you will need it to configure your Vue client. + +![Create project role "admin"](/img/vue/project-role.png) + +![Assign the "admin" role to your user](/img/vue/project-authz.png) + +## Vue setup + +Now that you have configured your web application on the ZITADEL side, you can proceed with the integration of your Vue client. + +### Install Vue dependencies + +npm install --save @zitadel/vue +To conveniently connect with ZITADEL, you can install the [@zitadel/vue NPM package](https://www.npmjs.com/package/@zitadel/vue). Run the following command: + +```bash +``` + +### Create and configure the auth service + +The @zitadel/vue package provides a `createZITADELAuth()` function which sets some defaults and calls the underlying [vue-oidc-client packages](https://github.com/soukoku/vue-oidc-client) `createOidcAuth()` function. +You can overwrite all the defaults with the aguments you pass to `createZITADELAuth()`. + +Export the object returned from `createZITADELAuth()` + +```ts reference +https://github.com/zitadel/zitadel-vue/blob/main/src/services/zitadelAuth.ts +``` + +### Register the auth service in your global variables when bootstrapping Vue + +```ts reference +https://github.com/zitadel/zitadel-vue/blob/main/src/main.ts +``` + +### Add three new views to your application + +The restricted admin view will only be shown if the user is authenticated and has the role "admin" in the apps project in ZITADEL. + +```ts reference +https://github.com/zitadel/zitadel-vue/blob/main/src/views/Admin.vue +``` + +The restricted login view is shown to all authenticated users. +It prints all the information it gets from the token and from the user info endpoint. + +```ts reference +https://github.com/zitadel/zitadel-vue/blob/main/src/views/Login.vue +``` + +The public no access view is shown to authenticated users who navigate to a page they don't have access to based on their roles. + +```ts reference +https://github.com/zitadel/zitadel-vue/blob/main/src/views/NoAccess.vue +``` + +### Add protected routes to your new pages as well as a Signout link + +Note that we conditionally render the admin view or the no access view based on the user's roles. + +```ts reference +https://github.com/zitadel/zitadel-vue/blob/main/src/router/index.ts +``` + +## Completion + +Congratulations! You have successfully integrated your Vue application with ZITADEL! + +If you get stuck, consider checking out the [ZITADEL Vue example application](https://github.com/zitadel/zitadel-vue). +This application includes all the functionalities mentioned in this quickstart. +You can start by cloning the repository and change the arguments to createZITADELAuth so they fit your requirements. +If you face issues, contact us or [raise an issue on GitHub](https://github.com/zitadel/zitadel-vue/issues). + +![App in console](/img/vue/app-screen.png) + +### What's next? + +Now that you have enabled authentication, you are ready to call add authorization to your application using ZITADEL APIs. +To do this, [refer to the API docs](/apis/introduction) or check out [the ZITADEL Console code on GitHub](https://github.com/zitadel/zitadel) which uses gRPC to access data. + +For more information on how to create an Vue application, you can refer to [Vue](https://vuejs.org/guide/quick-start.html). +If you want to learn more about the libraries wrapped by [@zitadel/vue](https://www.npmjs.com/package/@zitadel/vue), [read the docs for vue-oidc-client](https://github.com/soukoku/vue-oidc-client/wiki/V1-Docs). \ No newline at end of file diff --git a/docs/docs/examples/sdks.md b/docs/docs/examples/sdks.md index 7ac248b684..9efe49cf38 100644 --- a/docs/docs/examples/sdks.md +++ b/docs/docs/examples/sdks.md @@ -9,16 +9,17 @@ 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) | 🚧 [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` | +| Language / Framework | Link Github | User Authentication | Manage resources | Notes | +|----------------------|---------------------------------------------------------------|-----------------------------------------------------------|------------------|-------------------| +| Go | [zitadel-go](https://github.com/zitadel/zitadel-go) | 🚧 [WIP](https://github.com/zitadel/zitadel-go/tree/next) | ✔️ | `official` | +| Vue | [zitadel-vue](https://github.com/zitadel/zitadel-vue) | ✔️ | ❌ | `official` | +| .NET | [zitadel-net](https://github.com/smartive/zitadel-net) | ✔️ | ✔️ | `community` | +| Elixir | [zitadel_api](https://github.com/jshmrtn/zitadel_api) | ✔️ | ✔️ | `community` | +| 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` | +| JVM | 🚧 [WIP](https://github.com/zitadel/zitadel/discussions/3650) | ❓ | ❓ | TBD | +| Python | 🚧 [WIP](https://github.com/zitadel/zitadel/issues/3675) | ❓ | ❓ | TBD | ## Missing SDK diff --git a/docs/sidebars.js b/docs/sidebars.js index 276082eac4..71b8d8d49e 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -11,8 +11,9 @@ module.exports = { type: "category", label: "Frontend", items: [ - "examples/login/angular", "examples/login/react", + "examples/login/vue", + "examples/login/angular", "examples/login/flutter", "examples/login/nextjs", "examples/login/go", diff --git a/docs/static/img/vue/app-create.png b/docs/static/img/vue/app-create.png new file mode 100644 index 0000000000..860ee81fc9 Binary files /dev/null and b/docs/static/img/vue/app-create.png differ diff --git a/docs/static/img/vue/app-screen.png b/docs/static/img/vue/app-screen.png new file mode 100644 index 0000000000..28b26e0042 Binary files /dev/null and b/docs/static/img/vue/app-screen.png differ diff --git a/docs/static/img/vue/project-authz.png b/docs/static/img/vue/project-authz.png new file mode 100644 index 0000000000..c9f00680a2 Binary files /dev/null and b/docs/static/img/vue/project-authz.png differ diff --git a/docs/static/img/vue/project-role.png b/docs/static/img/vue/project-role.png new file mode 100644 index 0000000000..1366c6eeb6 Binary files /dev/null and b/docs/static/img/vue/project-role.png differ diff --git a/docs/static/img/vue/tick-refresh-token.png b/docs/static/img/vue/tick-refresh-token.png new file mode 100644 index 0000000000..cfcadaa28c Binary files /dev/null and b/docs/static/img/vue/tick-refresh-token.png differ