Skip to content

QUICKSTART.md

Latest commit

 

History

History
309 lines (233 loc) · 8.37 KB

QUICKSTART.md

File metadata and controls

309 lines (233 loc) · 8.37 KB

@asgardeo/vue Quickstart

This guide will help you quickly integrate Asgardeo authentication into your Vue.js application.

Prerequisites

  • Node.js (version 16 or later. LTS version recommended)
  • An Asgardeo account
  • Basic knowledge of Vue 3 and the Composition API

Step 1: Configure an Application in Asgardeo

  1. Sign in to Asgardeo Console

  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/<your-organization-name>)

  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:

# 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:

# 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:

cd vue-sample

Step 3: Install the SDK

Install the Asgardeo Vue SDK in your project:

# 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):

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: '<your-organization-base-url>',
  clientId: '<your-app-client-id>',
})

app.mount('#app')

Replace:

  • <your-organization-base-url> with the Base URL you noted in Step 1 (e.g., https://api.asgardeo.io/t/<your-organization-name>)
  • <your-app-client-id> with the Client ID from Step 1

Then wrap your app component with the AsgardeoProvider in src/App.vue:

<script setup>
import { AsgardeoProvider } from '@asgardeo/vue'
</script>

<template>
  <AsgardeoProvider>
    <!-- Your application content goes here -->
  </AsgardeoProvider>
</template>

Step 5: Add Sign-in & Sign-out to Your App

Update your src/App.vue to include sign-in and sign-out functionality:

<script setup lang="ts">
import { SignedIn, SignedOut, SignInButton, SignOutButton } from '@asgardeo/vue'
</script>

<template>
  <div>
    <SignedIn>
      <SignOutButton />
    </SignedIn>
    <SignedOut>
      <SignInButton />
    </SignedOut>
  </div>
</template>

<style scoped>
/* Your custom styles */
</style>

Step 6: Display User Information

You can also display user information by using the User component and the useUser composable:

<script setup lang="ts">
import { SignedIn, SignedOut, SignInButton, SignOutButton, User } from '@asgardeo/vue'
import { useUser } from '@asgardeo/vue'

const { user, isLoading } = useUser()
</script>

<template>
  <div>
    <SignedIn>
      <div v-if="!isLoading" class="user-info">
        <h1>Welcome, {{ user?.username }}</h1>
        <p>Email: {{ user?.email }}</p>
      </div>
      <div v-else>
        Loading user information...
      </div>
      <SignOutButton />
    </SignedIn>
    <SignedOut>
      <SignInButton />
    </SignedOut>
  </div>
</template>

<style scoped>
.user-info {
  padding: 1rem;
  border: 1px solid #e0e0e0;
  border-radius: 4px;
  margin-bottom: 1rem;
}

h1 {
  margin: 0 0 0.5rem 0;
  font-size: 1.5rem;
}

p {
  margin: 0;
  color: #666;
}
</style>

Using the User Render Function Pattern

Alternatively, you can use the User component with a render function:

<script setup lang="ts">
import { SignedIn, SignedOut, SignInButton, SignOutButton, User } from '@asgardeo/vue'
</script>

<template>
  <div>
    <SignedIn>
      <User v-slot="{ user, isLoading }">
        <div v-if="!isLoading" class="user-info">
          <h1>Welcome, {{ user.username }}</h1>
          <p>Email: {{ user.email }}</p>
        </div>
        <div v-else>
          Loading user information...
        </div>
      </User>
      <SignOutButton />
    </SignedIn>
    <SignedOut>
      <SignInButton />
    </SignedOut>
  </div>
</template>

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.

# 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:

<script setup lang="ts">
import { Callback } from '@asgardeo/vue'
</script>

<template>
  <div>
    <Callback />
  </div>
</template>

Next Steps

🎉 Congratulations! You've successfully integrated Asgardeo authentication into your Vue app.

What to explore next:

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

Getting Help

If you encounter issues:

  1. Check the FAQs
  2. Search GitHub Issues
  3. Ask on the WSO2 Community Forum
  4. Contact Asgardeo Support