Skip to content

Nuxt quickstart

Welcome to the Nuxt quickstart guide! In this document, you will learn to build a Nuxt app, add user login, and display user profile information using Asgardeo.

[//] STEPS_START

Configure an application in Asgardeo

  • Sign into the Asgardeo Console and navigate to Applications > New Application.
  • Select Traditional Web Application and complete the wizard by providing a suitable name, the OpenID Connect protocol, and an authorized redirect URL.

Example

Name: asgardeo-nuxt

Authorized redirect URL: http://localhost:3000/api/auth/callback

Once you finish creating the application, note down the following values from its Info tab. You will need them to configure the Asgardeo Nuxt SDK.

  • Client ID - The unique identifier for your application.
  • Client Secret - The confidential secret generated for your application.
  • Base URL - The base URL of your Asgardeo organization. This typically follows the format https://api.asgardeo.io/t/<your-organization-name>.

Info

The authorized redirect URL is the address Asgardeo sends the user back to after a successful sign-in. The SDK exposes this callback at /api/auth/callback, so for local development you must register http://localhost:3000/api/auth/callback.

Create a Nuxt app

Create your new Nuxt app.

npm create nuxt@latest asgardeo-nuxt
cd asgardeo-nuxt
npm run dev

yarn create nuxt@latest asgardeo-nuxt
cd asgardeo-nuxt
yarn dev

pnpm create nuxt@latest asgardeo-nuxt
cd asgardeo-nuxt
pnpm dev

Install @asgardeo/nuxt

The Asgardeo Nuxt SDK is shipped as a Nuxt module. It registers a Nitro server plugin that runs the OAuth flow, a set of API routes under /api/auth/*, and auto-imported components and composables you can use anywhere in your app. Stop the dev server before installing the module.

npm install @asgardeo/nuxt

yarn add @asgardeo/nuxt

pnpm add @asgardeo/nuxt

Set up environment variables

Create a .env file in the root of your Nuxt project. The Nuxt module reads NUXT_PUBLIC_* variables on the client and the unprefixed secrets on the server only.

.env
NUXT_PUBLIC_ASGARDEO_BASE_URL="https://api.asgardeo.io/t/<your-organization-name>"
NUXT_PUBLIC_ASGARDEO_CLIENT_ID="<your-app-client-id>"
NUXT_PUBLIC_ASGARDEO_AFTER_SIGN_OUT_URL="<after-sign-out-redirect-url>"
ASGARDEO_CLIENT_SECRET="<your-app-client-secret>"

Register the Asgardeo Nuxt module

Open nuxt.config.ts and add @asgardeo/nuxt to the modules array. The SDK reads the credentials you set in .env automatically — you only need to declare the module.

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@asgardeo/nuxt'],
});

The SDK reads your credentials from the environment variables automatically. You can optionally configure post sign-in / sign-out destinations in the asgardeo config block if needed.

Wrap your app with <AsgardeoProvider />

<AsgardeoProvider /> mounts the SDK's full provider tree (auth, user, organization, branding, theme) and exposes the SSR-hydrated state to every composable below it. The component is auto-registered by the module — you do not need to import it.

Replace the contents of app.vue with the following.

app.vue
<template>
  <AsgardeoProvider>
    <NuxtPage />
  </AsgardeoProvider>
</template>

Info

All SDK components are auto-registered (for example, SignedIn, SignInButton, UserDropdown). You can use them directly in any <template> without an explicit import.

Add sign-in and sign-out to your app

The Asgardeo Nuxt SDK provides <SignInButton /> and <SignOutButton /> to start and end a session. Combine them with <SignedIn /> and <SignedOut /> to render content based on the user's authentication state.

Create a pages/index.vue file (or replace its contents if it already exists) with the following.

pages/index.vue
<template>
  <header>
    <SignedOut>
      <SignInButton />
    </SignedOut>
    <SignedIn>
      <SignOutButton />
    </SignedIn>
  </header>
</template>

When the user clicks Sign In, the SDK calls /api/auth/signin, which redirects the browser to Asgardeo's sign-in page. After authentication, Asgardeo sends the user back to /api/auth/callback where the SDK exchanges the authorization code for tokens and issues the session cookie.

Display the signed-in user's profile information

The SDK provides several ways to access the signed-in user's profile information. You can use the User, UserProfile, or UserDropdown components to access and display user profile information in a declarative way.

  • <User />: Component provides a scoped slot (v-slot) pattern to access user profile information:
  • <UserProfile /> — Component provides a declarative way to display and update user profile information.
  • <UserDropdown /> — Component provides a dropdown menu with built-in user information and sign-out functionality.

Update pages/index.vue to render the dropdown and a personalized greeting.

pages/index.vue
<template>
  <header>
    <SignedOut>
      <SignInButton />
    </SignedOut>
    <SignedIn>
      <UserDropdown />
      <SignOutButton />
    </SignedIn>
  </header>

  <main>
    <SignedIn>
      <User v-slot="{ user }">
        <div>
          <p>Welcome back, {{ user.userName || user.username || user.sub }}</p>
        </div>
      </User>
      <UserProfile />
    </SignedIn>
  </main>
</template>

Protect a page with middleware

The Asgardeo Nuxt SDK provides a named middleware called asgardeoMiddleware that you can use to gate any route behind authentication. Unauthenticated visitors are redirected to the sign-in flow automatically.

Use definePageMeta to apply the asgardeoMiddleware middleware to any page. For example, create a pages/dashboard.vue:

pages/dashboard.vue
<script setup lang="ts">
  definePageMeta({ middleware: ['asgardeoMiddleware'] });
</script>

Choose how users will sign in

Before running the app, you need to decide how you want users to sign into your application:

When users click `Sign In`, your app redirects them to Asgardeo's sign-in page. After they sign in, it redirects them back to your app. This default behavior works without extra configurations.

Enable App-Native Authentication [//] SHOW_IF="data-quickstart=embedded"

The embedded sign-in functionality depends on the App-Native Authentication feature. This feature allows your app to authenticate users without redirecting them to the Asgardeo sign-in page.

To enable this feature, follow these steps:

  • Navigate to Asgardeo Console.
  • Go to Applications > Your App > Advanced.
  • Enable App-Native Authentication by checking the checkbox.

Info

Read more about App-Native Authentication to understand how it works.

Set up the in-app sign-in form [//] SHOW_IF="data-quickstart=embedded"

Create a dedicated sign-in page that renders the embedded form. Create pages/sign-in.vue:

pages/sign-in.vue
<template>
  <SignIn />
</template>

Then, update the .env file with the route for the sign-in page. Add the following line to your .env file:

.env
NUXT_PUBLIC_ASGARDEO_SIGN_IN_URL="/sign-in"

Run the app [//] SHOW_IF="data-quickstart=redirect,data-quickstart=embedded"

Start the dev server.

npm run dev

yarn dev

pnpm dev

Visit your app's homepage at http://localhost:3000.

Important

To try out sign-in and sign-out, create a test user in Asgardeo by following this guide.

[//] STEPS_END