Skip to content

Latest commit

 

History

History
105 lines (72 loc) · 4.9 KB

README.md

File metadata and controls

105 lines (72 loc) · 4.9 KB
Raw

@zitadel/vue Example

Authenticate your ZITADEL users within your Vue applications.

NPM Version NPM License PRs Welcome

Important

If you want to try out @zitadel/vue, read the ZITADEL step-by-step guide for Vue. It shows how to get the client_id and the project_resource_id from ZITADEL and how to wire everything up in Vue.

Project Structure

The example project is generated in the repositories root directory using Vite.

The following pages are added to the scaffolded example application:

  • src/views/Login.vue: The protected login page shows the information retrieved from ZITADEL when a user is authenticated.
  • src/views/Admin.vue: The protected admin page renders different views depending on if the user has the role "admin" or not.

Example GUI

The following files are added or modified to enable ZITADEL authentication:

  • src/router/index.ts: The routes are protected using the meta field authName and conditional lazy loading.
  • src/App.vue: The navigation bar is conditionally rendered depending on the authentication state.
  • src/services/zitadelAuth.ts: The @zitadel/vue SDK is configured.
  • The file src/main.ts shows how the Vue application is bootstrapped with ZITADEL auth support.
  • The folder ./lib contains the @zitadel/vue SDK.

Features

The NPM package @zitadel/vue wraps the NPM package vue-oidc-client. All vue-oidc-client features are available and the whole configuration can be overridden.

The following features are added to vue-oidc-client

  • @zitadel/vue defaults as much configuration as possible.
  • @zitadel/vue provides a simple way to check for user roles.
  • An example application is provided to show how to use @zitadel/vue.

The following is an example for a minimal OIDC configuration:

const zitadelAuth = createZITADELAuth({
   issuer: `${myZITADELInstancesOrigin}`,
   client_id: `${myApplicationsClientID}`,
   project_resource_id: `${myApplicationsProjectResourceID}`,
   organization_id: `${myApplicationsOrganizationID}`, // optional
})

The following defaults apply:

  • The OIDC Code Flow with PKCE is used for authentication at ZITADEL.
  • ZITADELs user info endpoint is called to enrich the user profile.
  • The access token is refreshed automatically by default before it expires.
  • If you specify a project_resource_id, the scopes for retrieving the users roles from the user info endpoint are added automatically. You can conveniently use zitadelAuth.hasRole("someRoleKey").

Optional:

  • add an organization_id to register and login users directly in the organization scope.

Running the Example

Recommended IDE Setup

VSCode + Volar (and disable Vetur) + TypeScript Vue Plugin (Volar).

Type Support for .vue Imports in TS

TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need TypeScript Vue Plugin (Volar) to make the TypeScript language service aware of .vue types.

If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a Take Over Mode that is more performant. You can enable it by the following steps:

  1. Disable the built-in TypeScript Extension
    1. Run Extensions: Show Built-in Extensions from VSCode's command palette
    2. Find TypeScript and JavaScript Language Features, right click and select Disable (Workspace)
  2. Reload the VSCode window by running Developer: Reload Window from the command palette.

Customize configuration

See Vite Configuration Reference.

Project Setup

yarn

Compile and Hot-Reload for Development

yarn dev

Type-Check, Compile and Minify for Production

yarn build

Lint with ESLint

yarn lint