Instructions for

Sign in to your SPA with Auth JS

About using Okta Auth JS with your SPA app

You can retain authentication control of your Vue.js single-page app (SPA) without redirection to Okta by implementing embedded authentication. Use embedded authentication with the help of the Auth JS and Vue.js libraries. These libraries provide you with common, reusable OAuth 2.0 methods and properties to handle the interaction between the authorization server and your client app.

You can customize the sign-in experience for your app with minimal use of low-level Okta Authentication and Okta OpenID Connect (OIDC) and OAuth 2.0 (opens new window) APIs.

The authentication interaction between the authorization server and your client app follows the Interaction Code flow. This flow is an extension to the OAuth 2.0 and OpenID Connect standard. It allows you to customize the user authentication experience for your app without redirecting to an authentication component outside of your app. See Implement authorization by Interaction Code grant type to understand the Interaction Code flow and necessary interactions between the authorization server and your app.

Note: You can use the Okta Sign-In Widget to quickly add embedded authentication if you don't need full customization capabilities for your sign-in user experience. The Sign-In Widget handles the Interaction Code flow in authentication use cases offered by Okta. See Sign in to your SPA with the embedded Okta Sign-In Widget.

Build Okta authentication with Auth JS in your SPA app

This guide explains how to build a password-only sign-in use case for your Vue.js app. See Next steps for other use cases.

Before you build or integrate your Vue.js app, ensure that you:

enable the Interaction Code grant on your default custom authorization server
register your Vue.js app in Okta by creating an app integration

If you don't have an existing Vue.js app, you can create a new basic Vue.js app from the Vue CLI.

Add Okta authentication to your Vue.js app with the following steps:

Install dependencies: Install Okta libraries for your integration.
Implement the basic sign-in flow:
- Set up the Okta configuration settings to initialize the Okta Auth JS instance with your app.
- Create a custom sign-in form and handle the response from the Auth JS SDK.
- Create the Vue.js app and instantiate the Okta Auth JS client.
- Create routes for your app.
- Connect the routes to the appropriate components.
When you're done building your Vue.js app, start your app to test your creation. Sign in with an existing user from your Okta org.

Create an Okta app integration

Before you integrate authentication to your Vue.js app, you must register your app in your org. This provides you with the OpenID Connect client ID for authentication requests from your app. Register your app by creating an app integration through the Okta Apps API (opens new window). You can also use the Admin Console with the following steps:

To create an app integration that represents your Vue.js app, sign in to your Admin Console (opens new window).
From the side navigation, select Applications and Resources > Applications, and then click Create App Integration.
In the dialog that appears, select OIDC - OpenID Connect as the Sign-in method, Single-Page Application as the Application type, and then click Next.

Fill in the following new app integration settings, and then click Save:

Setting	Value/Description
App integration name	Specify a unique name for your app.
Grant types	Leave Authorization Code selected, and then select Refresh Token. Click Advanced and select Interaction Code.
Sign-in redirect URIs	Specify your app URI for the callback redirect from Okta. For example: `http://localhost:8080/login/callback`
Sign-out redirect URIs	Specify your app sign-out redirect URI. For example: `http://localhost:8080`
Trusted Origins > Base URIs	Specify your app base URI for CORS. For example: `http://localhost:8080`
Assignments	Assign users to your app.

Select the Sign On tab and scroll down to the User authentication section. New apps are automatically assigned the shared default app sign-in policy (opens new window). This policy has a catch-all rule that allows a user access to the app using either one or two factors, depending on your org setup.
For this use case, Okta wants to use only the password factor. Click Edit and select the Password only preset policy (opens new window) to assign it to your app.
Click Save.

Note: Be sure to also update the policy rule of the password authenticator to not require any additional verification.

Note: You can verify that both CORS and redirect are enabled for your app using the Admin Console. Go to Security > API > Trusted Origins page in the Admin Console to review the configured trusted origins.

Ensure that Interaction Code, Refresh Token, and Authorization Code grant types are enabled for your app.

App integration settings

You need two pieces of information from your org and app integration for your Vue.js app:

Client ID: From the General tab of your app integration, save the generated Client ID value.
Issuer: From the General tab of your app integration, save the Okta domain value. Use your Okta domain value for the issuer setting that represents the authorization server. Use https://{yourOktaDomain}/oauth2/default as the issuer for your app if you're using the Okta Integrator Free Plan org. See Issuer configuration if you want to use another Okta custom authorization server.

Install the SDK

Create a Vue.js app (optional)

If you don't have an existing Vue.js app, you can quickly create an app by using the Vue CLI (opens new window):

npm install -g @vue/cli
vue create okta-app

Manually select the following features: defaults and Router.
Select 3.x for the Vue.js version.
Select Y for router history mode.

Go into your root app directory to view the created files:

cd okta-app

Install dependencies

Add the following information to your React app:

The latest version of Okta Auth JS (opens new window), @okta/okta-auth-js
The latest version Okta Vue.js (opens new window), @okta/okta-vue

And install them by using npm from your root app directory:

npm install @okta/okta-vue@latest
npm install @okta/okta-auth-js@latest

Build a basic password-only sign-in use case for your app. This use case is outlined in the following sequence diagram with your single-page app (SPA) as the client:

Sequence diagram that displays the interactions between the resource owner, SDK, authorization server, and resource server for a basic SPA password sign-in flow.

The steps in the following sections focus on the interaction between your client app, the user, and the Auth JS SDK.

Set up the Okta configuration settings

Before you code your forms and routes, use the required configuration settings to initialize your Auth JS instance:

clientId: Your client ID, {yourClientId}
issuer: The authorization server in your org (for example, https://{yourOktaDomain}/oauth2/default)
scopes: The required OAuth 2.0 scopes (opens new window) for your app
redirectUri: Set your callback redirect URI. This value must be configured in your app Sign-in redirect URIs and Trusted Origins lists.

You can create a src/config.js file to define your configuration settings. For example:

export default {
  oidc: {
    clientId: '{yourClientId}',
    issuer: 'https://{yourOktaDomain}/oauth2/default',
    redirectUri: '{yourLocalAppDomain}/login/callback',
    scopes: ['openid', 'offline_access', 'profile', 'email'],
    tokenManager: {
      storage: 'localStorage'
    }
  }
}

Note: See the Okta Auth JS configuration reference (opens new window) for more Auth JS client configurations.

Create a Vue component that displays the sign-in form and submits the authentication request to Okta. Then, handle the response from the authentication request, which follows the Interaction Code flow. For Auth JS Interaction Code methods, see the Auth JS Identity Engine module readme (opens new window).

For example, create a src/components/Login.vue file with the following content:

<template>
  <div class="login">
    <h1>Sign in</h1>
    <p v-if="$route.query.redirect">
      You need to sign in first.
    </p>
    <form @submit.prevent="signIn" autocomplete="off">
      Email: <label><input v-model="email" placeholder="email" v-focus></label><br><br>
      Password: <label><input v-model="pass" placeholder="password" type="password"></label><br>
      <br>
      <button type="submit">Continue</button>
      <p v-if="error" class="error">{{msg}}</p>
    </form>
  </div>
</template>

<script>
export default {
  data () {
    return {
      email: '',
      pass: '',
      msg: '',
      error: false
    }
  },
  methods: {
    signIn () {
      this.$auth.idx.authenticate({
      username: this.email,
      password: this.pass
    }).then(transaction => {
      switch (transaction.status) {
        case 'SUCCESS':
          this.$auth.tokenManager.setTokens(transaction.tokens)
          this.$router.replace(this.$route.query.redirect || '/')
          break
        case 'PENDING':
          // next IDX step not handled in this app yet
          this.error = true
          this.msg = transaction.messages[0].message
          console.log('TODO: add handling for status: ', transaction.status,
            'message: ', transaction.messages,
            'next step: ', transaction.nextStep)
          break
        case 'FAILURE':
          // failure from idx.authenticate
          this.error = true
          this.msg = transaction.messages[0].message
          console.log(transaction.status, transaction.messages)
          break
        default:
          this.error = true
          this.msg = transaction.messages[0].message
          console.error('What happened?: ', transaction.status, transaction.messages)
      }
    }).catch(err => {
      this.error = true
      this.msg = err.message
      console.error(err.message)
      })
    }
  }
}
</script>

<style>
  .error {
    color: red;
  }
</style>

Create the Vue.js app and instantiate the Okta Auth JS client

Create the Vue.js app definition by importing all the required libraries and instantiate the Okta Auth JS client with the settings from config.js. For example, create a src/main.js file with the following content:

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { OktaAuth } from '@okta/okta-auth-js'
import OktaVue from '@okta/okta-vue'
import sampleConfig from '@/config'

const oktaAuth = new OktaAuth(sampleConfig.oidc)

createApp(App)
.directive('focus', {
  // When the bound element is inserted into the DOM...
  mounted: function (el) {
    // Focus the element
    el.focus()
  }
})
.use(router)
.use(OktaVue, { oktaAuth,
  onAuthRequired: () => {
    router.push('/login')
  },
  onAuthResume: () => {
    router.push('/login')
  },
})
.mount('#app')

Create routes

Use the Vue Router (opens new window) and the Okta Vue SDK (opens new window) libraries to simplify your component and route definitions. Some routes require authentication to render and other routes don't. The following are some basic routes that you need to configure for your app:

A default page route to handle the landing page of the app
A login route to show your app sign-in page
A protected route for authenticated users to access protected content

Default page route

To create the default /index page, update the src/App.vue file to provide links to relevant locations in your app. Then, provide a link to your sign-in page, a link to sign-out of your authenticated session, and links to authenticated pages by using the authState object (see authStateManager in Auth JS SDK (opens new window)).

You can use the following condition to hide or show specific elements:

v-if="authState && !authState.isAuthenticated"

See the following src/App.vue file example:

<template>
  <div id="app">
    <h1>Okta Vue.js and Auth JS example</h1>
      <div id="nav">
        <router-link to="/about">About</router-link> |
        <router-link to="/dashboard" v-if="authState && authState.isAuthenticated" >Dashboard</router-link>
        <span v-if="authState && authState.isAuthenticated"> | </span>
        <a v-if="authState && authState.isAuthenticated" v-on:click="logout()"> Sign out</a>
        <router-link v-if="authState && !authState.isAuthenticated" to="/login">Sign in</router-link>
      </div>
    <template v-if="$route.matched.length">
      <router-view></router-view>
    </template>
    <template v-else>
      <h2>Welcome!</h2>
      <p>This is an embedded Okta auth SPA app with Vue.js and Auth JS SDK</p>
      <p>You are {{ (authState && authState.isAuthenticated) ? '' : 'not' }} signed in.</p>
    </template>
  </div>
</template>

<script>
export default {
  name: 'app',
  methods: {
      async logout () {
        await this.$auth.signOut()
      }
    }
}
</script>

...

This route directs the user to your app sign-in page. See the Login route component, specified in the src/components/Login.vue file, from Create the sign-in component.

Protected route

Create a protected route that is only available to users with a valid accessToken:

You can provide access to a protected route when the requiresAuth metadata is added in the route definition.

For example, this snippet from the src/router/index.js router file provides access to the /dashboard component only if the requiresAuth metadata is true:
```
{ path: '/dashboard', name: 'Dashboard', component: Dashboard, meta: { requiresAuth: true } },
```
You can use the authState.isAuthenticated property in the default route landing page to determine if you need to show a protected element.

For example, this snippet from the App.vue file provides access to the /dashboard component only if authState.isAuthenticated is true:
```
<router-link to="/dashboard" v-if="authState && authState.isAuthenticated" >Dashboard</router-link>
```
Note: The authState.isAuthenticated property is true if both accessToken and idToken are valid.

In this protected /dashboard component example, the src/components/Dashboard.vue file is created to show basic information from the ID token. Retrieve ID token information by using the $auth (opens new window) instance from the Okta Vue SDK and calling the $auth.getUser() (opens new window) function from the Okta Auth JS SDK.

<template>
  <div>
    <h1>Dashboard</h1>
    <h3>Success</h3>
       <p>
       You have signed in to an embedded Okta auth SPA app with Vue.js and Auth JS SDK.
       </p>
    <h3>User Profile</h3>
    <br><br>
    <table>
      <thead>
        <tr>
          <th>Claim</th>
          <th>Value</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="(claim, index) in claims" :key="index">
          <td>{{claim.claim}}</td>
          <td :id="'claim-' + claim.claim">{{claim.value}}</td>
        </tr>
      </tbody>
    </table>
  </div>
</template>

<script>
export default {
  name: 'Dashboard',
  data () {
    return {
      claims: []
    }
  },
  async created () {
    this.claims = await Object.entries(await this.$auth.getUser()).map(entry => ({ claim: entry[0], value: entry[1] }))
  }
}
</script>

...

Note: You can extend the set of claims by modifying the scope settings in your Okta configuration to retrieve custom information about the user. This includes locale, address, groups, and more (opens new window).

Connect the routes

This route definition example uses the Vue Router (opens new window) and the Okta Vue SDK (opens new window) in the src/router/index.js file. Notice that the requiresAuth metadata must be true for protected routes.

import { createRouter, createWebHistory } from 'vue-router'
import { navigationGuard } from '@okta/okta-vue'
import About from '@/components/About.vue'
import Dashboard from '@/components/Dashboard.vue'
import Login from '@/components/Login.vue'

const router = createRouter({
  history: createWebHistory(__dirname),
  routes: [
    { path: '/', name: 'Home', component: About },
    { path: '/about', name: 'About', component: About },
    { path: '/dashboard', name: 'Dashboard', component: Dashboard, meta: { requiresAuth: true } },
    { path: '/login', component: Login }
  ]
})

router.beforeEach(navigationGuard)

export default router;

Note: The Okta Vue SDK (opens new window) provides navigation guard logic to circumvent the navigational guard mixins issue in vue-router-next.

Start your app

To run and test your app, execute:

npm run serve

Open a browser and go to your app URL. Try to sign in to your app with an existing user from your org.

Next steps

After you create a basic sign-in flow for the Vue.js app, you can extend your app's sign-in experience. You can add features such as Multifactor Authentication, self-registration, or social IdP authentication.

For each of those features, ensure that you understand the Interaction Code flow so that you can handle possible remediation steps of the interaction. In addition to implementing remediation steps for those features in your app code, you need to configure authenticators and app sign-in policies for your app. See these pages for more information:

Note: The Admin Console and the Okta API support the Identity Engine org configuration.

Note: For use cases that require a callback route for email magic link or for social IdP redirect, use the Okta Vue SDK (opens new window). It provides the LoginCallback (opens new window) component. You can use the component to handle token parsing, token storage, and redirecting to a protected page after a user is authenticated.

On this page