diff --git a/packages/nextjs/QUICKSTART.md b/packages/nextjs/QUICKSTART.md deleted file mode 100644 index 7781965d6..000000000 --- a/packages/nextjs/QUICKSTART.md +++ /dev/null @@ -1,283 +0,0 @@ -# `@asgardeo/nextjs` Quickstart - -This guide will help you quickly integrate Asgardeo authentication into your Next.js application using Auth.js. - -## Prerequisites - -- [Node.js](https://nodejs.org/en/download) (version 18 or later. LTS version recommended) -- An [Asgardeo account](https://wso2.com/asgardeo/docs/get-started/create-asgardeo-account/) -- About 15 minutes - -## Step 1: Configure an Application in Asgardeo - -1. **Sign in to Asgardeo Console** - - Go to [Asgardeo Console](https://console.asgardeo.io/) - - Sign in with your Asgardeo account - -2. **Create a New Application** - - Click **Applications** in the left sidebar - - Click **+ New Application** - - Choose **Traditional Web Application** - - Enter your application name (e.g., "Teamspace") - -3. **Note Down Your Credentials from the `Quickstart` tab** - - From the **Protocol** tab: - - Copy the **Client ID** - - Copy the **Client Secret** - - From the **Info** tab: - - Copy the **Issuer URL** - -4. **Configure Application Settings from the `Protocol` tab** - - **Authorized redirect URLs**: Add your callback URL - - `http://localhost:3000` - - Click **Update** to save the configuration - -## Step 2: Create a Next.js Application - -If you don't have a Next.js application set up yet, you can create one: - -```bash -# Using npm -npm create next-app@latest next-sample -- --yes -cd next-sample - -# Using pnpm -pnpm create next-app@latest next-sample -- --yes -cd next-sample - -# Using yarn -yarn create next-app next-sample -- --yes -cd next-sample -``` - -## Step 3: Install the SDK - -Install the Asgardeo Next.js SDK in your project: - -```bash -# Using npm -npm install @asgardeo/nextjs - -# Using pnpm -pnpm add @asgardeo/nextjs - -# Using yarn -yarn add @asgardeo/nextjs -``` - -## Step 4: Setup Environment Variables - -Create a `.env` file in your project root and add the following environment variables. Replace the placeholders with the values you copied from Asgardeo in Step 1. - -**.env** - -```bash -NEXT_PUBLIC_ASGARDEO_BASE_URL="https://api.asgardeo.io/t/" -NEXT_PUBLIC_ASGARDEO_CLIENT_ID="" -ASGARDEO_CLIENT_SECRET="" -``` - -## Step 5: Setup the Middleware - -Create a `middleware.ts` file in your project root to handle authentication: - -```bash -import { AsgardeoNext } from '@asgardeo/nextjs'; -import { NextRequest } from 'next/server'; - -const asgardeo = new AsgardeoNext(); - -asgardeo.initialize({ - baseUrl: process.env.NEXT_PUBLIC_ASGARDEO_BASE_URL, - clientId: process.env.NEXT_PUBLIC_ASGARDEO_CLIENT_ID, - clientSecret: process.env.ASGARDEO_CLIENT_SECRET, -}); - -export async function middleware(request: NextRequest) { - return await asgardeo.middleware(request); -} - -export const config = { - matcher: [ - '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', - '/(api|trpc)(.*)', - ], -}; -``` - -## Step 6: Configure the Provider - -Wrap your application with the `AsgardeoProvider` in your main entry file i.e. `app/layout.tsx`: - -```tsx -import type { Metadata } from "next"; -import { Geist, Geist_Mono } from "next/font/google"; -import {AsgardeoProvider} from '@asgardeo/nextjs'; -import "./globals.css"; - -const geistSans = Geist({ - variable: "--font-geist-sans", - subsets: ["latin"], -}); - -const geistMono = Geist_Mono({ - variable: "--font-geist-mono", - subsets: ["latin"], -}); - -export const metadata: Metadata = { - title: "Create Next App", - description: "Generated by create next app", -}; - -export default function RootLayout({ - children, -}: Readonly<{ - children: React.ReactNode; -}>) { - return ( - - - {children} - - - ); -} -``` - -## Step 7: Add Sign-in & Sign-out to Your App - -Update your `app/page.tsx` to include sign-in and sign-out functionality: - -```tsx -import {SignInButton, SignedIn, SignOutButton, SignedOut} from '@asgardeo/nextjs'; - -export default function Home() { - return ( - <> - - - - - - - - ); -} -``` - -## Step 8: Display User Information - -You can also display user information by using the `User` component & the `UserProfile` component: - -```tsx -import { SignedIn, SignedOut, SignInButton, SignOutButton, User, UserProfile } from '@asgardeo/nextjs'; - -export default function Home() { - return ( - <> - - - {({ user }) => ( -
-

Welcome, {user.username}

-
- )} - - - - - - - - - ); -} -``` - -## Step 9: Try Login - -Run your application and test the sign-in functionality. You should see a "Sign In" button when you're not signed in, and clicking it will redirect you to the Asgardeo sign-in page. - -```bash -# Using npm -npm run dev - -# Using pnpm -pnpm dev - -# Using yarn -yarn dev -``` - -## Step 10: Embedded Login Page (Optional) - -If you want to use an embedded login page instead of redirecting to Asgardeo, you can use the `SignIn` component: - -Configure the path of the sign-in page in the `middleware.ts` file: - -```diff -import { AsgardeoNext } from '@asgardeo/nextjs'; -import { NextRequest } from 'next/server'; - -const asgardeo = new AsgardeoNext(); - -asgardeo.initialize({ - baseUrl: process.env.NEXT_PUBLIC_ASGARDEO_BASE_URL, - clientId: process.env.NEXT_PUBLIC_ASGARDEO_CLIENT_ID, - clientSecret: process.env.ASGARDEO_CLIENT_SECRET, -+ signInUrl: '/signin', -}); - -export async function middleware(request: NextRequest) { - return await asgardeo.middleware(request); -} - -export const config = { - matcher: [ - '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)', - '/(api|trpc)(.*)', - ], -}; -``` - -Then, create a new page for the sign-in component in `app/signin/page.tsx`: - -```tsx -'use client'; - -import {SignIn} from '@asgardeo/nextjs'; - -export default function SignInPage() { - return ; -} -``` - -Once you have set this up, clicking on the "Sign In" button will render the embedded login page instead of redirecting to Asgardeo. - -## Next Steps - -🎉 **Congratulations!** You've successfully integrated Asgardeo authentication into your Next.js app. - -### What to explore next: - -- **User Profile Management** - Access and display detailed user profile information -- **Protected Routes** - Implement route-level authentication using middleware -- **Custom Styling** - Customize the appearance of your authentication flow -- **Session Management** - Learn about managing user sessions and tokens -- **Error Handling** - Implement proper error handling for authentication flows - -### Common Issues - -- **Redirect URL Mismatch**: Ensure your redirect URL in Asgardeo matches exactly: `http://localhost:3000` -- **Environment Variables**: Double-check that all environment variables are correctly set in `.env` - -### Additional Resources - -- **[Auth.js Documentation](https://authjs.dev/)** - Learn more about Auth.js features and configuration -- **[Asgardeo Documentation](https://wso2.com/asgardeo/docs/)** - Comprehensive guide to Asgardeo features -- **[Next.js Documentation](https://nextjs.org/docs)** - Learn more about Next.js features and best practices - -For more help, visit the [Asgardeo Documentation](https://wso2.com/asgardeo/docs/) or check out our [examples](../../examples/). diff --git a/packages/react/QUICKSTART.md b/packages/react/QUICKSTART.md deleted file mode 100644 index 2ab5543de..000000000 --- a/packages/react/QUICKSTART.md +++ /dev/null @@ -1,178 +0,0 @@ -# `@asgardeo/react` Quickstart - -This guide will help you quickly integrate Asgardeo authentication into your React application. - -## Prerequisites - -- [Node.js](https://nodejs.org/en/download) (version 16 or later. LTS version recommended) -- An [Asgardeo account](https://wso2.com/asgardeo/docs/get-started/create-asgardeo-account/) - -## Step 1: Configure an Application in Asgardeo - -1. **Sign in to Asgardeo Console** - - Go to [Asgardeo Console](https://console.asgardeo.io/) - - Sign in with your Asgardeo account - -2. **Create a New Application** - - Click **Applications** in the left sidebar - - Click **+ New Application** - - Choose **Single Page Application (SPA)** - - Enter your application name (e.g., "Teamspace") - -3. **Note Down Your Credentials from the `Quickstart` tab** - - Copy the **Client ID** from the application details - - Note your **Base URL** (ex: `https://api.asgardeo.io/t/`) - -4. **Configure Application Settings from the `Protocol` tab** - - **Authorized redirect URLs**: Add your application URLs - - `https://localhost:5173` - - **Allowed origins**: Add the same URLs as above - - Click **Update** to save the configuration - -## Step 2: Create a React Application - -If you don't have a React application set up yet, you can create one using Vite: - -```bash -# Using npm -npm create vite@latest react-sample --template react - -# Using pnpm -pnpm create vite@latest react-sample --template react - -# Using yarn -yarn create vite react-sample --template react -``` - -## Step 3: Install the SDK - -Install the Asgardeo React SDK in your project: - -```bash -# Using npm -npm install @asgardeo/react - -# Using pnpm -pnpm add @asgardeo/react - -# Using yarn -yarn add @asgardeo/react -``` - -## Step 4: Configure the Provider - -Wrap your application with the `AsgardeoProvider` in your main entry file i.e. `src/main.tsx`: - -```tsx -import { StrictMode } from 'react' -import { createRoot } from 'react-dom/client' -import './index.css' -import App from './App.tsx' -import { AsgardeoProvider } from '@asgardeo/react' - -createRoot(document.getElementById('root')!).render( - - - - - -) -``` - -Replace: -- `` with the Base URL you noted in Step 1 (e.g., `https://api.asgardeo.io/t/`) -- `` with the Client ID from Step 1 - -## Step 5: Add Sign-in & Sign-out to Your App - -Update your `App.tsx` to include sign-in and sign-out functionality: - -```tsx -import { SignedIn, SignedOut, SignInButton, SignOutButton } from '@asgardeo/react' -import './App.css' - -function App() { - return ( - <> - - - - - - - - ) -} - -export default App -``` - -## Step 6: Display User Information - -You can also display user information by using the `User` component & the `UserProfile` component: - -```tsx -import { SignedIn, SignedOut, SignInButton, SignOutButton, User, UserProfile } from '@asgardeo/react' -import './App.css' - -function App() { - return ( - <> - - - {({ user }) => ( -
-

Welcome, {user.username}

-
- )} - - - - - - - - - ) -} - -export default App -``` - -## Step 7: Try Login - -Run your application and test the sign-in functionality. You should see a "Sign In" button when you're not signed in, and clicking it will redirect you to the Asgardeo sign-in page. - -```bash -# Using npm -npm run dev - -# Using pnpm -pnpm dev - -# Using yarn -yarn dev -``` - -## Next Steps - -🎉 **Congratulations!** You've successfully integrated Asgardeo authentication into your React app. - -### What to explore next: - -- **[Complete Guide](./COMPLETE%20GUIDE.md)** - Learn about advanced features and customization -- **[API Documentation](./API.md)** - Explore all available components and hooks -- **Custom Styling** - Customize the appearance of authentication components -- **Protected Routes** - Implement route-level authentication -- **User Profile Management** - Access and manage user profile data - -### Common Issues - -- **Redirect URL Mismatch**: Ensure your redirect URLs in Asgardeo match your local/production URLs exactly -- **CORS Errors**: Make sure to add your domain to the "Allowed Origins" in your Asgardeo application settings -- **Client ID Issues**: Double-check that you're using the correct Client ID from your Asgardeo application - -For more help, visit the [Asgardeo Documentation](https://wso2.com/asgardeo/docs/) or check out our [examples](../../examples/). diff --git a/packages/vue/QUICKSTART.md b/packages/vue/QUICKSTART.md deleted file mode 100644 index b400bec82..000000000 --- a/packages/vue/QUICKSTART.md +++ /dev/null @@ -1,309 +0,0 @@ -# `@asgardeo/vue` Quickstart - -This guide will help you quickly integrate Asgardeo authentication into your Vue.js application. - -## Prerequisites - -- [Node.js](https://nodejs.org/en/download) (version 16 or later. LTS version recommended) -- An [Asgardeo account](https://wso2.com/asgardeo/docs/get-started/create-asgardeo-account/) -- Basic knowledge of Vue 3 and the Composition API - -## Step 1: Configure an Application in Asgardeo - -1. **Sign in to Asgardeo Console** - - Go to [Asgardeo Console](https://console.asgardeo.io/) - - Sign in with your Asgardeo account - -2. **Create a New Application** - - Click **Applications** in the left sidebar - - Click **+ New Application** - - Choose **Single Page Application (SPA)** - - Enter your application name (e.g., "My Vue App") - -3. **Note Down Your Credentials from the `Quickstart` tab** - - Copy the **Client ID** from the application details - - Note your **Base URL** (ex: `https://api.asgardeo.io/t/`) - -4. **Configure Application Settings from the `Protocol` tab** - - **Authorized redirect URLs**: Add your application URLs - - `https://localhost:5173` - - **Allowed origins**: Add the same URLs as above - - Click **Update** to save the configuration - -## Step 2: Create a Vue Application - -If you don't have a Vue application set up yet, you can create one using `create-vue`: - -```bash -# Using npm -npm create vue@latest vue-sample - -# Using pnpm -pnpm create vue@latest vue-sample - -# Using yarn -yarn create vue vue-sample -``` - -When prompted, enable TypeScript for a better development experience. - -Alternatively, using Vite: - -```bash -# Using npm -npm create vite@latest vue-sample --template vue-ts - -# Using pnpm -pnpm create vite@latest vue-sample --template vue-ts - -# Using yarn -yarn create vite vue-sample --template vue-ts -``` - -Navigate to your project: - -```bash -cd vue-sample -``` - -## Step 3: Install the SDK - -Install the Asgardeo Vue SDK in your project: - -```bash -# Using npm -npm install @asgardeo/vue - -# Using pnpm -pnpm add @asgardeo/vue - -# Using yarn -yarn add @asgardeo/vue -``` - -## Step 4: Configure the Provider - -Register the Asgardeo plugin and wrap your application with the `AsgardeoProvider` in your main entry file (`src/main.ts`): - -```ts -import { createApp } from 'vue' -import './style.css' -import App from './App.vue' -import { AsgardeoPlugin, AsgardeoProvider } from '@asgardeo/vue' - -const app = createApp(App) - -app.use(AsgardeoPlugin, { - baseUrl: '', - clientId: '', -}) - -app.mount('#app') -``` - -Replace: -- `` with the Base URL you noted in Step 1 (e.g., `https://api.asgardeo.io/t/`) -- `` with the Client ID from Step 1 - -Then wrap your app component with the `AsgardeoProvider` in `src/App.vue`: - -```vue - - - -``` - -## Step 5: Add Sign-in & Sign-out to Your App - -Update your `src/App.vue` to include sign-in and sign-out functionality: - -```vue - - - - - -``` - -## Step 6: Display User Information - -You can also display user information by using the `User` component and the `useUser` composable: - -```vue - - - - - -``` - -### Using the User Render Function Pattern - -Alternatively, you can use the `User` component with a render function: - -```vue - - - -``` - -## Step 7: Try Login - -Run your application and test the sign-in functionality. You should see a "Sign In" button when you're not signed in, and clicking it will redirect you to the Asgardeo sign-in page. - -```bash -# Using npm -npm run dev - -# Using pnpm -pnpm dev - -# Using yarn -yarn dev -``` - -Open your browser and navigate to `http://localhost:5173` (or the port shown in your terminal). Click the "Sign In" button to test the authentication flow. - -## Step 8: Handle Callback - -The SDK automatically handles the OAuth callback redirect. Make sure your application loads correctly after returning from Asgardeo. For custom callback handling, you can use the `Callback` component: - -```vue - - - -``` - -## Next Steps - -🎉 **Congratulations!** You've successfully integrated Asgardeo authentication into your Vue app. - -### What to explore next: - -- **[API Documentation](https://wso2.com/asgardeo/docs/sdks/vue/overview)** - Learn about all available composables and components -- **[Composables Guide](https://wso2.com/asgardeo/docs/sdks/vue/composables)** - Master the composable API (`useUser`, `useOrganization`, etc.) -- **[Custom Styling](https://wso2.com/asgardeo/docs/sdks/vue/customization/styling)** - Customize the appearance of authentication components -- **[Protected Routes](https://wso2.com/asgardeo/docs/sdks/vue/protected-routes)** - Implement route-level authentication -- **[Organizations/Workspaces](https://wso2.com/asgardeo/docs/sdks/vue/organizations)** - Implement multi-tenancy features -- **[User Profile Management](https://wso2.com/asgardeo/docs/sdks/vue/user-profile)** - Access and manage user profile data -- **[Social Login](https://wso2.com/asgardeo/docs/sdks/vue/social-login)** - Enable sign-in with Google, GitHub, Microsoft, and Facebook - -## Common Issues - -### Redirect URL Mismatch -- **Problem**: Getting errors about redirect URI not matching -- **Solution**: Ensure your redirect URLs in Asgardeo match your local/production URLs exactly (including protocol and port) - -### CORS Errors -- **Problem**: Getting CORS-related errors in the console -- **Solution**: Make sure to add your domain to the "Allowed Origins" in your Asgardeo application settings - -### Client ID Not Found -- **Problem**: Authentication fails with "Client ID is invalid" -- **Solution**: Double-check that you're using the correct Client ID from your Asgardeo application and that it's properly configured in the plugin options - -### Plugin Not Registered -- **Problem**: Vue warns about plugin not being registered -- **Solution**: Make sure you've called `app.use(AsgardeoPlugin, { ... })` before mounting your app - -### State Not Updating -- **Problem**: User state doesn't update after sign-in -- **Solution**: Ensure you're using the composable (`useUser`) inside a component wrapped with `AsgardeoProvider` - -## More Resources - -- [Asgardeo Documentation](https://wso2.com/asgardeo/docs/) -- [Vue.js Documentation](https://vuejs.org/) -- [SDK Examples](../../samples/) -- [GitHub Repository](https://github.com/asgardeo/asgardeo-auth-vue-sdk) - -## Getting Help - -If you encounter issues: -1. Check the [FAQs](https://wso2.com/asgardeo/docs/faq/) -2. Search [GitHub Issues](https://github.com/asgardeo/asgardeo-auth-vue-sdk/issues) -3. Ask on the [WSO2 Community Forum](https://wso2.com/community/) -4. Contact [Asgardeo Support](https://wso2.com/asgardeo/support/) diff --git a/packages/vue/README.md b/packages/vue/README.md index 2354f54ef..0dd6cb112 100644 --- a/packages/vue/README.md +++ b/packages/vue/README.md @@ -24,7 +24,7 @@ The Asgardeo Vue SDK provides a streamlined way to integrate secure authenticati ## Quick Start -Get started with Asgardeo in your Vue application in minutes. Follow our [Vue Quick Start Guide](./QUICKSTART.md) for step-by-step instructions on integrating authentication into your app. +Get started with Asgardeo in your Vue application in minutes. Follow our [Vue Quick Start Guide](https://wso2.com/asgardeo/docs/quick-starts/vue/) for step-by-step instructions on integrating authentication into your app. ## Installation