README
@auth0/auth0-vue
Auth0 SDK for Vue Applications using Authorization Code Grant Flow with PKCE.
⚠️ This is a beta release of the Vue SDK for Auth0. As with all beta software, this should not be considered stable or suitable for production use. If you have any feedback on this release, please create an issue.
Table of Contents
- Documentation
- Installation
- Getting Started
- Contributing
- Support + Feedback
- Frequently Asked Questions
- Vulnerability Reporting
- What is Auth0
- License
Documentation
Installation
Using npm:
npm install @auth0/auth0-vue@beta
Using yarn:
yarn add @auth0/auth0-vue@beta
Getting Started
- Auth0 Configuration
- Configuring the plugin
- Add login to your application
- Display the user profile
- Add logout to your application
- Calling an API
- Accessing ID Token claims
- Error Handling
- Protect a route
Auth0 Configuration
Create a Single Page Application in the Auth0 Dashboard.
If you're using an existing application, verify that you have configured the following settings in your Single Page Application:
- Click on the "Settings" tab of your application's page.
- Ensure that "Token Endpoint Authentication Method" under "Application Properties" is set to "None"
- Scroll down and click on the "Show Advanced Settings" link.
- Under "Advanced Settings", click on the "OAuth" tab.
- Ensure that "JsonWebToken Signature Algorithm" is set to
RS256
and that "OIDC Conformant" is enabled.
Next, configure the following URLs for your application under the "Application URIs" section of the "Settings" page:
- Allowed Callback URLs:
http://localhost:3000
- Allowed Logout URLs:
http://localhost:3000
- Allowed Web Origins:
http://localhost:3000
These URLs should reflect the origins that your application is running on. Allowed Callback URLs may also include a path, depending on where you're handling the callback (see below).
Take note of the Client ID and Domain values under the "Basic Information" section. You'll need these values in the next step.
Configuring the plugin
Create an instance of the Auth0Plugin
by calling createAuth0
and pass it to Vue's app.use()
.
import { createAuth0 } from '@auth0/auth0-vue';
const app = createApp(App);
app.use(
createAuth0({
domain: '<AUTH0_DOMAIN>',
client_id: '<AUTH0_CLIENT_ID>',
redirect_uri: '<MY_CALLBACK_URL>'
})
);
app.mount('#app');
Add login to your application
In order to add login to your application you can use the loginWithRedirect
function that is exposed on the return value of useAuth0
, which you can access in your component's setup
function.
<script>
import { useAuth0 } from '@auth0/auth0-vue';
export default {
setup() {
const { loginWithRedirect } = useAuth0();
return {
login: () => {
loginWithRedirect();
}
};
}
};
</script>
Once setup returns the correct method, you can call that method from your component's HTML.
<template>
<div>
<button @click="login">Log in</button>
</div>
</template>
Using Options API
<template>
<div>
<button @click="login">Log in</button>
</div>
</template>
<script>
export default {
methods: {
login() {
this.$auth0.loginWithRedirect();
}
}
};
</script>
Display the user profile
To display the user's information, you can use the reactive user
property exposed by the return value of useAuth0
, which you can access in your component's setup
function.
<script>
import { useAuth0 } from '@auth0/auth0-vue';
export default {
setup() {
const { loginWithRedirect, user } = useAuth0();
return {
login: () => {
loginWithRedirect();
},
user
};
}
};
</script>
Once setup returns the SDK's reactive property, you can access that property from your component's HTML.
<template>
<div>
<h2>User Profile</h2>
<button @click="login">Log in</button>
<pre>
<code>{{ user }}</code>
</pre>
</div>
</template>
Note: Ensure the user is authenticated by implementing login in your application before accessing the user's profile.
Using Options API
<template>
<div>
<h2>User Profile</h2>
<button @click="login">Log in</button>
<pre>
<code>{{ user }}</code>
</pre>
</div>
</template>
<script>
export default {
data: function () {
return {
user: this.$auth0.user
};
},
methods: {
login() {
this.$auth0.loginWithRedirect();
}
}
};
</script>
Add logout to your application
Adding logout to your application you be done by using the logout
function that is exposed on the return value of useAuth0
, which you can access in your component's setup
function.
<script>
import { useAuth0 } from '@auth0/auth0-vue';
export default {
setup() {
const { logout } = useAuth0();
return {
logout: () => {
logout({ returnTo: window.location.origin });
}
};
}
};
</script>
Once setup returns the correct method, you can call that method from your component's HTML.
<template>
<div>
<button @click="logout">Log out</button>
</div>
</template>
Using Options API
<template>
<div>
<button @click="logout">Log out</button>
</div>
</template>
<script>
export default {
methods: {
logout() {
this.$auth0.logout({ returnTo: window.location.origin });
}
}
};
</script>
Calling an API
To call an API, configure the plugin by setting the audience
to the API Identifier of the API in question:
import { createAuth0 } from '@auth0/auth0-vue';
const app = createApp(App);
app.use(
createAuth0({
domain: '<AUTH0_DOMAIN>',
client_id: '<AUTH0_CLIENT_ID>',
redirect_uri: '<MY_CALLBACK_URL>',
audience: '<AUTH0_AUDIENCE>'
})
);
app.mount('#app');
After configuring the plugin, you will need to retrieve an Access Token and set it on the Authorization
header of your request.
Retrieving an Access Token can be done by using the getAccessTokenSilently
function that is exposed on the return value of useAuth0
, which you can access in your component's setup
function.
<script>
import { useAuth0 } from '@auth0/auth0-vue';
export default {
setup() {
const { getAccessTokenSilently } = useAuth0();
return {
doSomethingWithToken: async () => {
const token = await getAccessTokenSilently();
const response = await fetch('https://api.example.com/posts', {
headers: {
Authorization: `Bearer ${token}`
}
});
const data = await response.json();
}
};
}
};
</script>
Using Options API
<script>
export default {
methods: {
async doSomethingWithToken() {
const token = await this.$auth0.getAccessTokenSilently();
const response = await fetch('https://api.example.com/posts', {
headers: {
Authorization: `Bearer ${token}`
}
});
const data = await response.json();
}
}
};
</script>
Accessing ID Token claims
To get access to the user's claims, you can use the reactive idTokenClaims
property exposed by the return value of useAuth0
, which you can access in your component's setup
function.
<script>
import { useAuth0 } from '@auth0/auth0-vue';
export default {
setup() {
const { loginWithRedirect, idTokenClaims } = useAuth0();
return {
login: () => {
loginWithRedirect();
},
idTokenClaims
};
}
};
</script>
Once setup returns the SDK's reactive property, you can access that property from your component's HTML.
<template>
<div>
<h2>ID Token Claims</h2>
<button @click="login">Log in</button>
<pre>
<code>{{ idTokenClaims }}</code>
</pre>
</div>
</template>
Using Options API
<template>
<div>
<h2>ID Token Claims</h2>
<button @click="login">Log in</button>
<pre>
<code>{{ idTokenClaims }}</code>
</pre>
</div>
</template>
<script>
export default {
data: function () {
return {
idTokenClaims: this.$auth0.idTokenClaims
};
},
methods: {
login() {
this.$auth0.loginWithRedirect();
}
}
};
</script>
Error Handling
When using this SDK, it could be the case that it is unable to correctly handle the authentication flow for a variety of reasons (e.g. an expired session with Auth0 when trying to get a token silently). In these situations, calling the actual methods will result in an exception being thrown (e.g. login_required
). On top of that, these errors are made available through the SDK's reactive error
property:
<script>
import { useAuth0 } from '@auth0/auth0-vue';
export default {
setup() {
const { error } = useAuth0();
return {
error
};
}
};
</script>
Once setup returns the SDK's error
property, you can access that property from your component's HTML.
<template>
<div>
<h2>Error Handling</h2>
<pre>
<code>{{ error?.error }}</code>
</pre>
</div>
</template>
Using Options API
<template>
<div>
<h2>Error Handling</h2>
<pre>
<code>{{ error?.error }}</code>
</pre>
</div>
</template>
<script>
export default {
data: function () {
return {
error: this.$auth0.error
};
}
};
</script>
Protect a route
If you are using our Auth0-Vue SDK with Vue-Router, you can protect a route by using the Navigation Guard provided by the SDK.
import { createApp } from 'vue';
import { createRouter, createWebHashHistory } from 'vue-router';
import { createAuth0, createAuthGuard } from '@auth0/auth0-vue';
const app = createApp(App);
app.use(createRouter({
routes: [
{
path: '/',
name: 'home',
component: Home
},
{
path: '/profile',
name: 'profile',
component: Profile,
beforeEnter: createAuthGuard(app)
}
],
history: createWebHashHistory()
}));
app.use(createAuth0({ ... }));
app.mount('#app');
Applying the guard to a route, as shown above, will only allow access to authenticated users. When a non-authenticated user tries to access a protected route, the SDK will redirect the user to Auth0 and redirect them back to your application's redirect_uri
(which is configured in createAuth0
, see Configuring the plugin). Once the SDK is done processing the response from Auth0 and exchanging it for tokens, the SDK will redirect the user back to the protected route they were trying to access initially.
Contributing
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
- Auth0's general contribution guidelines
- Auth0's code of conduct guidelines
- This repo's contribution guide
Support + Feedback
For support or to provide feedback, please raise an issue on our issue tracker.
Frequently Asked Questions
For a rundown of common issues you might encounter when using the SDK, please check out the FAQ.
Vulnerability Reporting
Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
What is Auth0?
Auth0 helps you to easily:
- implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
- log in users with username/password databases, passwordless, or multi-factor authentication
- link multiple user accounts together
- generate signed JSON Web Tokens to authorize your API calls and flow the user identity securely
- access demographics and analytics detailing how, when, and where users are logging in
- enrich user profiles from other data sources using customizable JavaScript rules
License
This project is licensed under the MIT license. See the LICENSE file for more info.