Instructions for

Sign in to your SPA with the embedded Okta Sign-In Widget

Instructions for

Note: This document is only for Identity Engine. See Identify your Okta solution (opens new window) to determine your Okta version.

This guide discusses how to build a password-only sign-in flow Vue.js app that uses the Okta Sign-In Widget for Okta-embedded authentication.

Learning outcomes

Understand the sequence of steps required to add the Okta Sign-In Widget to a Vue.js app for embedded authentication.
Understand how to run the Vue.js embedded authentication sample app.

What you need

Okta Integrator Free Plan org
Okta Auth JavaScript SDK (opens new window) (@okta/okta-auth-js)
Okta Vue.js SDK (opens new window) (@okta/okta-vue)
Okta Sign-In Widget (opens new window) (@okta/okta-signin-widget)—see the Okta Sign-In Widget guide.
Vue CLI (opens new window)

Note: Use the latest version of the Okta libraries for your Vue.js app.

Sample code

Embedded Vue.js sample app with the Okta Sign-In Widget (opens new window)—see Run the sample app.

If you want to deploy a Vue.js single-page app (SPA) in the embedded authentication model, where your app retains authentication control without redirection to Okta, then you can use the Okta Sign-In Widget to quickly add authentication. The Okta Sign-In Widget is a JavaScript library that includes support for full sign-in features with Okta so that the amount of authentication code you have to write for your app is minimal.

This guide explains how to build a password-only sign-in flow for your Vue.js app. Before you build or integrate your Vue.js app, ensure that you perform the following steps:

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.

Integrate the Sign-In Widget to your Vue.js app to add Okta authentication with the following steps:

Install dependencies: Install Okta libraries for your integration.
Load the Sign-In Widget: Create the Sign-In Widget instance and a wrapper for the Widget to be rendered as a Vue.js component.
Create routes: Create the routes for your app.
Connect the routes: Connect your routes to the appropriate components.
When you’re done integrating the Sign-In Widget to your Vue.js app, start your app to test your creation. Sign in with an existing user from your Okta org.

See Run the sample Vue.js app for an example of a simple embedded authentication Vue.js app that uses the Okta libraries.

Note: These steps are described in detail from the linked sections of this guide.

Create an Okta app integration

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

In the Admin Console, go to Applications and Resources > Applications.
Click Create App Integration.
Select OIDC - OpenID Connect as the Sign-in method.
Select Single-Page Application for the Application Type, and then click Next.
On the New Single-Page App Integration page, enter the following information:
- Enter an app name.
- Select the Refresh Token checkbox.
- Select Advanced in the Grant type section, and then select the Interaction Code checkbox.
  
  Note: If the Interaction Code checkbox doesn’t appear, the Interaction Code grant type isn’t enabled for your org. To enable it, go to Settings > Account > Embedded widget sign-in support. See Verify that the Interaction Code grant type is enabled.
- Set Sign-in redirect URIs to a URI that’s appropriate for your app. For example, http://localhost:8080/login/callback if you're using the sample app.
- Set Sign-out redirect URIs to a URI that’s appropriate for your app. For example, http://localhost:8080 if you're using the sample app.
In the Assignments section, select Allow everyone in your organization to access, and then click Save.
In the General Settings section on the General tab, click Edit.
Under EMAIL VERIFICATION EXPERIENCE set the Callback URI to a URI that’s appropriate for your app. For example, http://localhost:8080/login/callback if you're using the sample app.
Click Save.
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, you want 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: Remember to update the password authenticator policy rule to not require any additional verification.
Verify that the custom authorization server uses the Interaction Code grant type.

Go to Security > API > Authorization Servers.
Select the default server.
Edit the Default Policy Rule.
Click Advanced in the IF Grant type is section and ensure that the Interaction Code checkbox is selected.

Note: If the Interaction Code checkbox doesn’t appear, the Interaction Code grant type isn’t enabled for your org. To enable it, go to Settings > Account > Embedded widget sign-in support. See Verify that the Interaction Code grant type is enabled.

In the Security > API > Trusted Origins page, ensure that there’s an entry for your sign-in redirect URI. See Enable CORS.

Okta org app integration configuration settings

You need two pieces of information from your org and app integration for your React 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 an Okta Integrator Free Plan org. See Issuer configuration if you want to use another Okta custom authorization server.

Install the SDK

Create a new Vue.js app (optional)

If you don't have an existing Vue.js app, you can quickly create a new 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

To install the latest version of the Okta Sign-In Widget (opens new window) locally through npm, run the following command in your project root folder:

npm install @okta/okta-signin-widget@latest

You also need the latest version of the Okta Vue.js SDK (opens new window)(@okta/okta-vue) for route protection and the latest version of the Okta Auth JS SDK (opens new window) (@okta/okta-auth-js) for widget dependencies:

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

Set up the Okta configuration settings

Use the required configuration settings to initialize your Sign-In Widget and your Auth JS instance:

clientId: Your client ID — {yourClientId}
issuer: The authorization server in your Okta org (for example, https://{yourOktaDomain}/oauth2/default)
pkce: Set this option to true to enable PKCE in the widget. This is used for SPA apps that use the Authentication Code with PKCE flow.
scopes: Set the OAuth 2.0 scopes that your app requires.
redirectUri: Set your callback redirect URI. This value must be configured in your Okta app Sign-in redirect URIs and the URI host must be in the Trusted Origins list.

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', 'profile', 'email'],
    pkce: true,
  }
}

Important: In Okta Sign-In Widget version 7+, Identity Engine is enabled by default. If you’re using an earlier version than 7, you must explicitly enable Identity Engine features by setting useInteractionCodeFlow: true in the configuration settings shown above. If you’re using version 7+ and you want to use Classic Engine rather than Identity Engine, specify useClassicEngine: true in the configuration settings.

Note: The baseUrl configuration setting isn't required in the Sign-In Widget for OIDC applications as of version 5.15.0 (opens new window). The ['openid', 'profile', 'email'] scopes are the most commonly used. See Scopes (opens new window).

Instantiate Okta authentication

Add Okta authentication by instantiating OktaAuth with the settings from Set up the Okta configuration settings in your main.js file:

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)
  .use(router)
  .use(OktaVue, {
    oktaAuth,
    onAuthRequired: () => {
      router.push('/login')
    },
    onAuthResume: () => {
      router.push('/login')
    },
  })
  .mount('#app')

To render the Sign-In Widget in Vue.js, you must create a wrapper that allows your app to treat it as a Vue component. For example, create a src/components/Login.vue file with the following content:

<template>
  <div class="login">
    <div id="okta-signin-container"></div>
  </div>
</template>

<script>
import OktaSignIn from '@okta/okta-signin-widget'
import '@okta/okta-signin-widget/css/okta-sign-in.min.css'

import sampleConfig from '../config'

export default {
  name: 'Login',
  mounted: function () {
    this.$nextTick(function () {
      const { issuer, clientId, redirectUri, scopes } = sampleConfig.oidc
      this.widget = new OktaSignIn({
        clientId,
        redirectUri,
        logo: require('@/assets/logo.png'),
        i18n: {
          en: {
            'primaryauth.title': 'Sign in to my Okta Sign-In Widget Vue.js app'
          }
        },
        authParams: {
          issuer,
          scopes,
        }
      })

      const originalUri = this.$auth.getOriginalUri();
      if (!originalUri) {
        this.$auth.setOriginalUri('/');
      }

      // Search for URL Parameters to see if a user is being routed to the application to recover password
      var searchParams = new URL(window.location).searchParams;
      this.widget.otp = searchParams.get('otp');
      this.widget.state = searchParams.get('state');

      this.widget.showSignInToGetTokens({
        el: '#okta-signin-container',
        scopes
      }).then(tokens => {
        this.$auth.handleLoginRedirect(tokens)
      }).catch(err => {
        throw err
      })

    })
  },
  unmounted () {
    // Remove the widget from the DOM on path change
    this.widget.remove()
  }
}
</script>

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 in order to render and others don't. The following are some basic routes that you need to configure for your app:

A default page to handle basic control of the app
A login route to show the Sign-In Widget
A callback route to parse tokens after a redirect from Okta
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. You need to provide a Login link to render the Sign-In Widget, a Logout link to sign-out of your authenticated session, and links to authenticated pages by using the authState object (see authStateManager in the 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="nav">
    <router-link to="/">Home</router-link> |
    <router-link to="/about">About</router-link> |
    <router-link to="/login" v-if="authState && !authState.isAuthenticated">Login</router-link>
    <router-link to="/profile" v-if="authState && authState.isAuthenticated">Protected Profile<router-link>
    <button v-if="authState && authState.isAuthenticated" v-on:click="logout()">Logout</button>
  </div>
  <router-view/>
</template>

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

<style>

...

This route hosts the Sign-In Widget and redirects if the user is already signed in. See the Login route component, specified in the src/components/Login.vue file, from Create a Sign-In Widget container.

Callback route

The Okta Vue SDK (opens new window) provides the LoginCallback (opens new window) component for the callback route. It handles token parsing, token storage, and redirecting to a protected page after a user is authenticated.

See how the callback route component is called from the route definition file (src/router/index.js) in the Connect the routes section.

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.

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

This snippet from the App.vue file provides access to the /profile component only if authState.isAuthenticated is true:
```
<router-link to="/profile" v-if="authState && authState.isAuthenticated">Protected Profile</router-link>
```

Note: The authState.isAuthenticated property is true if both accessToken and idToken are valid.

In this protected /profile component example, the src/components/Profile.vue file is created to show basic information from the ID token. Retrieve ID token information 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 class="profile">
    <h1 class="ui header">
      <i aria-hidden="true" class="drivers license outline icon">
      </i>
      My User Profile (ID Token Claims)
    </h1>
    <p>
      This route is protected with the <code>onAuthRequired</code>, navigation guard which will ensure that this page cannot be accessed until you have authenticated.
    </p>
    <table class="ui 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: 'Profile',
  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 Sign-In Widget scopes (opens new window) settings 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 { LoginCallback } from '@okta/okta-vue'
import { navigationGuard } from '@okta/okta-vue'
import Home from '../views/Home.vue'
import LoginComponent from '@/components/Login.vue'
import ProfileComponent from '@/components/Profile.vue'

const routes = [
  {
    path: '/',
    name: 'Home',
    component: Home
  },
  {
    path: '/about',
    name: 'About',
    component: () => import(/* webpackChunkName: "about" */ '../views/About.vue')
  },
  {
    path: '/login',
    name: 'Login',
    component: LoginComponent
  },
  {
    path: '/login/callback',
    component: LoginCallback
  },
  {
    path: '/profile',
    component: ProfileComponent,
    meta: {
      requiresAuth: true
    }
  }
]

const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes
})

router.beforeEach(navigationGuard)

export default router

Note The Okta Vue SDK (opens new window) provides navigation guard logic to circumvent 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 navigate to your app URL. Try to sign in to your app with an existing user from your Okta org.

Run the sample app

You can run the sample embedded Sign-In Widget Vue.js app (opens new window) to quickly view a simple working Vue.js app with the Sign-In Widget.

Ensure that you set up your Okta org for a password factor only use case and create an app integration in Okta for your sample app.
Download the sample app: git clone https://github.com/okta/samples-js-vue.git
Go to the custom-login directory: cd samples-js-vue/custom-login
Install the app and its dependencies: npm install
Set the environment variables with your Okta org app integration configuration settings:

export ISSUER=https://{yourOktaDomain}/oauth2/default
export CLIENT_ID={yourAppClientId}
export USE_INTERACTION_CODE=true

Run the app: npm start
Open a browser window and navigate to the app's home page: http://localhost:8080 (opens new window). Try to sign in to the sample app with an existing user from your Okta org.

On this page

Sign in to your SPA with the embedded Okta Sign-In Widget

Create an Okta app integration

Okta org app integration configuration settings

Install the SDK

Run the sample app

Next steps

See also

On this page

Sign in to your SPA with the embedded Okta Sign-In Widget

About using the Sign-In Widget with your SPA app

Create an Okta app integration

Okta org app integration configuration settings

Install the SDK

Load the Sign-In Widget

Basic sign-in flow

Run the sample app

Next steps

See also