From 6286d21500121ce651ef575be2e2901681e122bd Mon Sep 17 00:00:00 2001 From: xiao-kong-long <53474978+xiao-kong-long@users.noreply.github.com> Date: Sat, 2 Mar 2024 14:13:57 +0800 Subject: [PATCH] feat: add nuxt document (#607) * feat: add nuxt document * Update sdk.md --------- Co-authored-by: Eric Luo --- docs/how-to-connect/nuxt.md | 160 ++++++++++++++++++++++++++++++++++++ docs/how-to-connect/sdk.md | 14 ++-- sidebars.js | 1 + 3 files changed, 169 insertions(+), 6 deletions(-) create mode 100644 docs/how-to-connect/nuxt.md diff --git a/docs/how-to-connect/nuxt.md b/docs/how-to-connect/nuxt.md new file mode 100644 index 000000000..fb68677cc --- /dev/null +++ b/docs/how-to-connect/nuxt.md @@ -0,0 +1,160 @@ +--- +title: Nuxt +description: Using Casdoor in a Nuxt project +keywords: [nuxt] +authors: [xiao-kong-long] +--- + +[nuxt-auth](https://github.com/casdoor/nuxt-auth) is an example of how to integrate casdoor in a nuxt project. We will guide you through the steps below. Many steps are similar to nextjs-auth. + +## Step 1: Deploy Casdoor + +Firstly, Casdoor should be deployed. + +You can refer to the Casdoor official documentation for the [Server Installation](/docs/basic/server-installation). Please deploy your Casdoor instance in **production mode**. + +After a successful deployment, make sure the following: + +- Open your favorite browser and visit ****. You will see the login page of Casdoor. +- Test the login functionality by entering `admin` as the username and `123` as the password. + +After that, you can quickly implement a Casdoor-based login page in your own app using the following steps. + +## Step 2: Add Middleware + +Middleware allows you to run code before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly. + +Create `.js` or `.ts` files in `middleware` directory in the root of your project to define Middleware. And the filenames are identified as the names of middleware. For example, in [nuxt-auth](https://github.com/casdoor/nuxt-auth), we create a file named `myMiddleware.js` in `middleware` directory, which can be refrenced as `myMiddleware` in other places like `nuxt.config.js`. + +### Example + +```js +//define which paths Middleware will run on +const protectedRoutes = ["/profile"]; + +export default function ({route, redirect}) { + + if (protectedRoutes.includes(route.path)) { + //redirect the incoming request to a different URL + redirect('/login'); + } +} +``` + +To make middleware work, you should add router in `nuxt.config.js`, like that: + +```js +export default { + // other configuations + + // what to add + router: { + middleware: ['myMiddleware'] // replace to your middleware name + }, +} + +``` + +See nuxt official documentation [middleware](https://nuxt.com/docs/guide/directory-structure/middleware) for more details. + +## Step 3: Use Casdoor SDK + +### 1.Install the SDK + +First, install `casdoor-js-sdk` via NPM or Yarn: + +```shell +npm install casdoor-js-sdk +``` + +Or: + +```shell +yarn add casdoor-js-sdk +``` + +### 2.Initializing the SDK + +Then initialization 6 string-type parameters in the following order: + +| Name | Required | Description | +|--------------------|----------|-----------------------------------------------------| +| serverUrl | Yes | Casdoor Server URL, such as `http://localhost:8000` | +| clientId | Yes | Application client ID | +| clientSecret | Yes | Application client secret | +| organizationName | Yes | Application organization | +| appName | Yes | Application name | +| redirectPath | Yes | redirected URL | + +### Example + +```js +const sdkConfig = { + serverUrl: "https://door.casdoor.com", + clientId: "294b09fbc17f95daf2fe", + clientSecret: "dd8982f7046ccba1bbd7851d5c1ece4e52bf039d", + organizationName: "casbin", + appName: "app-vue-python-example", + redirectPath: "/callback", +}; +``` + +:::caution + +Replace the configuration values with your own Casdoor instance, especially the `clientId`, `clientSecret`, and `serverUrl`. + +::: + +### 3.Redirect to the Login Page + +When you need to authenticate users who access your app, you can send the target URL and redirect to the login page provided by Casdoor. + +Make sure you have added the callback URL (e.g. ****) in the application configuration beforehand. + +```js +const CasdoorSDK = new Sdk(sdkConfig); +CasdoorSDK.signin_redirect(); +``` + +### 4.Get Token and Storage + +After the Casdoor verification is passed, it will redirect back to your application with token. + +You can opt in to use cookie to storage the token. + +```js +CasdoorSDK.exchangeForAccessToken() + .then((res) => { + if (res && res.access_token) { + //Get Token + return CasdoorSDK.getUserInfo(res.access_token); + } + }) + .then((res) => { + // Storage Token + Cookies.set("casdoorUser", JSON.stringify(res)); + }); +``` + +You can refer to the Casdoor official documentation for the [How to use Casdoor SDK](https://casdoor.org/docs/how-to-connect/sdk/#how-to-use-casdoor-sdk). + +## Step 4: Add Middleware Authentication Function + +when users attempt to access a protected route, Middleware Authentication function verifies their identity. If the user is not authenticated, they are redirected to a login page or denied access. + +### Example + +```js +import Cookies from "js-cookie"; + +const protectedRoutes = ["/profile"]; + +export default function ({route, redirect}) { + const casdoorUserCookie = Cookies.get('casdoorUser'); + const isAuthenticated = !!casdoorUserCookie; + + if (!isAuthenticated && protectedRoutes.includes(route.path)) { + redirect('/login'); + } +} +``` diff --git a/docs/how-to-connect/sdk.md b/docs/how-to-connect/sdk.md index f69446451..1660a1b11 100644 --- a/docs/how-to-connect/sdk.md +++ b/docs/how-to-connect/sdk.md @@ -37,12 +37,14 @@ SDK: `casdoor-js-sdk` or React SDK: `casdoor-react-sdk` or Vue SDK: `casdoor-vue | .NET Desktop SDK | For .NET desktop apps | [casdoor-dotnet-sdk](https://github.com/casdoor/casdoor-dotnet-sdk) | WPF: [casdoor-dotnet-desktop-example](https://github.com/casdoor/casdoor-dotnet-desktop-example)
WinForms: [casdoor-dotnet-winform-example](https://github.com/casdoor/casdoor-dotnet-winform-example)
[Avalonia UI](https://avaloniaui.net/): [casdoor-dotnet-avalonia-example](https://github.com/RVShershnev/casdoor-dotnet-avalonia-example) | | C/C++ SDK | For C/C++ desktop apps | [casdoor-cpp-sdk](https://github.com/casdoor/casdoor-cpp-sdk) | [casdoor-cpp-qt-example](https://github.com/casdoor/casdoor-cpp-qt-example) | -| Web frontend SDK | Description | SDK code | Example code | -|-------------------|----------------------------------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Javascript SDK | For traditional non-SPA websites | [casdoor-js-sdk](https://github.com/casdoor/casdoor-js-sdk) | Nodejs backend: [casdoor-raw-js-example](https://github.com/casdoor/casdoor-raw-js-example)
Go backend: [casdoor-go-react-sdk-example](https://github.com/casdoor/casdoor-go-react-sdk-example) | -| Frontend-only SDK | For frontend-only SPA websites | [casdoor-js-sdk](https://github.com/casdoor/casdoor-js-sdk) | [casdoor-react-only-example](https://github.com/casdoor/casdoor-react-only-example) | -| React SDK | For React websites | [casdoor-react-sdk](https://github.com/casdoor/casdoor-react-sdk) | Nodejs backend: [casdoor-nodejs-react-example](https://github.com/casdoor/casdoor-nodejs-react-example)
Java backend: [casdoor-spring-security-react-example](https://github.com/casdoor/casdoor-spring-security-react-example) | -| Next.js SDK | For Next.js websites | | [nextjs-auth](https://github.com/casdoor/nextjs-auth) | +| Web frontend SDK | Description | SDK code | Example code | +|-------------------|----------------------------------|-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Javascript SDK | For traditional non-SPA websites | [casdoor-js-sdk](https://github.com/casdoor/casdoor-js-sdk) | Nodejs backend: [casdoor-raw-js-example](https://github.com/casdoor/casdoor-raw-js-example)
Go backend: [casdoor-go-react-sdk-example](https://github.com/casdoor/casdoor-go-react-sdk-example) | +| Frontend-only SDK | For frontend-only SPA websites | [casdoor-js-sdk](https://github.com/casdoor/casdoor-js-sdk) | [casdoor-react-only-example](https://github.com/casdoor/casdoor-react-only-example) | +| React SDK | For React websites | [casdoor-react-sdk](https://github.com/casdoor/casdoor-react-sdk) | Nodejs backend: [casdoor-nodejs-react-example](https://github.com/casdoor/casdoor-nodejs-react-example)
Java backend: [casdoor-spring-security-react-example](https://github.com/casdoor/casdoor-spring-security-react-example) | +| Next.js SDK | For Next.js websites | | [nextjs-auth](https://github.com/casdoor/nextjs-auth) | +| Nuxt SDK | For Nuxt websites | | [nuxt-auth](https://github.com/casdoor/nuxt-auth) | + | Vue SDK | For Vue websites | [casdoor-vue-sdk](https://github.com/casdoor/casdoor-vue-sdk) | [casdoor-python-vue-sdk-example](https://github.com/casdoor/casdoor-python-vue-sdk-example) | | Angular SDK | For Angular websites | [casdoor-angular-sdk](https://github.com/casdoor/casdoor-angular-sdk) | [casdoor-nodejs-angular-example](https://github.com/casdoor/casdoor-nodejs-angular-example) | | Flutter SDK | For Flutter Web websites | [casdoor-flutter-sdk](https://github.com/casdoor/casdoor-flutter-sdk) | [casdoor-flutter-example](https://github.com/casdoor/casdoor-flutter-example) | diff --git a/sidebars.js b/sidebars.js index eb06e59aa..8981845d7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -76,6 +76,7 @@ module.exports = { }, "how-to-connect/plugin", "how-to-connect/nextjs", + "how-to-connect/nuxt", "how-to-connect/oauth", "how-to-connect/cas", {