@privyid/nuxt-oauth2
v1.1.0
Published
PrivyID's OAuth2 module for your Nuxt.js app
Downloads
32
Keywords
Readme
@privyid/nuxt-oauth2 PrivyID's OAuth2 module for your Nuxt.js app. Bootstrapped from SohoHouse/nuxt-oauth.
Contents
Usage
Requirements
- Nuxt
- Universal deployment (i.e. a server rendered app, not an SPA)
- a Vuex store
Get Setup
Install the dependency:
# yarn
yarn add @privyid/nuxt-oauth2
# npm
npm install @privyid/nuxt-oauth2
Add to your nuxt.config.js
and configure:
// nuxt.config.js
modules: ['@privyid/nuxt-oauth2'],
oauth: {
sessionName: 'mySession',
secretKey: process.env.SECRET_KEY,
oauthHost: process.env.OAUTH_HOST,
oauthClientID: process.env.OAUTH_CLIENT_ID,
oauthClientSecret: process.env.OAUTH_CLIENT_SECRET,
authPath: process.env.AUTH_PATH || '/admin', // optional
authorizeUrl: process.env.AUTHORIZE_URL, // optional
accessTokenUrl: process.env.ACCESS_TOKEN_URL, // optional
// onLogout & fetchUser is optional
onLogout: (req, res) => {
// do something after logging out
},
fetchUser: (accessToken, request) => {
// do something to return the user
const user = User.findByToken(accessToken, request)
return user
}
}
For TypeScript users only
Add to your tsconfig.json
{
"types": ["@privyid/nuxt-oauth2"]
}
Use in your application
- Use the access token as you'd like from the Vuex store:
// any-component.vue
export default {
mounted() {
const { accessToken } = this.$store.state.oauth
// fetch more details from somewhere...
},
}
- Mark your authenticated page components (
@privyid/nuxt-oauth2
will ensure users are logged in before accessing these pages):
// secret.vue
export default {
authenticated: true,
name: 'MySecretComponent',
}
Configuration
| Option | Required? | Description |
| :------------------ | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sessionName
| * | Configure the name of the cookie that @privyid/nuxt-oauth2 uses |
| secretKey
| * | Provide a secret key to sign the encrypted cookie. Do not leak this! |
| oauthHost
| * | Host of your OAuth provider (usually ending in oauth
or oauth2
). Can be string or function receiving args (req)
|
| oauthClientId
| * | Client ID of your application, registered with your OAuth provider. Can be string or function receiving args (req)
|
| oauthClientSecret
| * | Client ID of your application, registered with your OAuth provider. Can be string or function receiving args (req)
|
| encrypt
| | Encrypt the OAuth access token |
| tokenName
| | Change the default access token name in Vuex store token |
| scopes
| | An array of scopes to authenticate against |
| authorizationUrl
| | The path to redirect users to authenticate (defaults to ${oauth_host}/authorize
) |
| accessTokenUrl
| | The path to request the access token (defaults to ${oauth_host}/token
) |
| authPath
| | The redirect auth login path. Default to /
|
| basePath
| | The base path for the OAuth scheme. |
| forceHTTPS
| | Force HTTPS redirect URL |
| moduleName
| | The name of the vuex module to be created by @privyid/nuxt-oauth2. (defaults to oauth
) |
| onLogout
| | Optional hook which is called after logging out. E.g. can be used to perform a full log out on your OAuth provider. Receives args (req, res, redirectUrl)
. Can be asynchronous (or return a promise). |
| fetchUser
| | Optional hook which is called when logging in to fetch your user object. Receives args (accessToken, request, options)
. |
| testMode
| | Flag which tells the module to ignore the OAuth dance and log every one in (see here for more). |
Dynamic Configuration
To dynamically set configuration at runtime, oauthHost
, oauthClientID
, oauthClientSecret
can be strings but also can be async
functions which accept req
as their only argument. This can be useful to choose configuration based on the URL or headers of the request.
Helpers
You can also use the functionality manually. @privyid/nuxt-oauth2
injects the following helpers into your store, components and ctx.app
: $login
and $logout
. Use these to manually log your user in or out.
Following a successful login/logout, your user will be redirected back to the page from which the helper was called (you can pass a redirectUrl
to the helpers to override this). For a full example, see below.
<!-- any-component.vue -->
<template>
<a @click="logout" v-if="loggedIn">Log Out</a>
<a @click="login" v-else>Log In</a>
</template>
<script>
export default {
asyncData({ app }) {
// Use from context
app.$login()
}
computed () {
loggedIn () {
return this.$store.state.oauth.accessToken
}
},
methods: {
login () {
// defaults to redirecting back to the current page
this.$login()
},
logout () {
// customise the redirrect url
const redirectUrl = '/my-target-path'
this.$logout(redirectUrl)
}
}
}
</script>
Encryption
You can also encrypt the OAuth access token simply by adding encrypt
to your nuxt.config.js
. Want to decrypt? Ask admin how to do it.
With your tests
Set options.oauth.testMode
to true
to tell the module to skip authentication. Using this, along with the fetchUser
option, can be helpful in e2e tests to stub your test users.
Develop
git clone https://github.com/privy-open-source/nuxt-oauth2.git
cd nuxt-oauth2
yarn
Running locally
To run the fixture Nuxt app (/test/e2e/fixture
) locally, make sure to:
cp .env.example .env
and populate with your real values. Then, run:
yarn dev
To boot the app locally.
License
The module is available as open source under the terms of the MIT License.