NuxtIAM

Concepts

Understanding the following concepts will help you work with Nuxt IAM faster.

Both Backend and Frontend

Nuxt IAM is both frontend and backend. The main authentication and authorization logic takes place in the backend. Nuxt IAM adds authentication and authorization components, pages, api routes, and logic to your Nuxt app allowing your app to have authentication and authorization logic. All the components, pages, api routes, and logic are 100% customizable so you can change things any way you want.

Server

Nuxt IAM uses Nuxt's server engine Nitro and the entire backend is built on it. Nuxt IAM adds the following directories to your server/api directory.

  • iam/authn: authentication handler
  • iam/refresh-tokens: refresh tokens handler
  • iam/users: global users handler
  • iam/doodads: an example api handler that you can use to copy and paste and quickly create api handlers of your own

Backend for Frontend

Nuxt IAM uses the Backend For Frontend (BFF) architectural pattern to increase the security of your Nuxt application. A BFF pattern allows Nuxt IAM to provide the best security practices for any client. Nuxt IAM differentiates between two types of clients: browsers and apps. It does this by requiring that every request contain the client-platform header.

Every client needs to send the client-platform header on every request.

client-platform is a required header and it must be sent with every request. Client platform allows Nuxt IAM to provide the best practices for securing your app. client-platform must be:

  • app: Use app if the request is coming from a non-browser such as a mobile app, tablet, or a tool like POSTMAN. Access and refresh tokens will be sent in the response headers. This is designed to be used in production.
  • browser: Use browser if the request is coming from a browser. Access and refresh tokens will be sent in secure, httpOnly cookies. This is designed to be used in production.
  • browser-dev: Use browser-dev if the request is coming from a browser in a development environment. Access and refresh tokens are sent in unsecure cookies. Use only in development.

Database

Nuxt IAM requires a database to operate successfully, and uses Prisma as its object relation mapper (ORM). For database configuration, please see Configuration.

Tokens

Nuxt IAM uses signed JSON web tokens (JWT) as part of its security. There are two types of tokens used: access tokens and refresh tokens. Access tokens allow a user to access a restricted resource, and refresh tokens allow a user to get a new pair of tokens.

Access Tokens

Access tokens are JWT tokens that grant an authenticated user access to a particular resource. For example, if a user wants to access their profile, they need to login with their correct email and password combination. If successful, Nuxt IAM will create an access token and refresh token and send them back to the client.

If the client is an app, the tokens will be sent in the header as iam-access-token for the access token, and iam-refresh-token for the refresh token.

If the client is a browser, the tokens will be sent in cookies. If the client-platform is browser, the cookies will be secure, if the client-platform is browser-dev, the cookies will be unsecure.

Access tokens expire every 15 minutes. Once an access token expires, the client will be unable to access the resource, and will need to log in. New tokens can be obtained using a valid refresh token. If you use the pages provided by Nuxt IAM, your access and refresh tokens will be automatically replaced once Nuxt IAM detects that the access token has expired.

If your refresh token expires, you must log in again.

Refresh Tokens

Refresh tokens are JWT tokens that are used to get new access and refresh tokens. They expire every 14 days. If your access token expires, you'll need to login again. You can get a new set of access and refresh tokens when you send a POST request to /api/iam/authn/refresh with an unexpired refresh token. If your refresh token has expired, you will not be able to get a new set of tokens and you'll need to login.

Every authenticated user can only have one active refresh token at a time.

Automatic token rotation

If your client platform is browser or browser-only, Nuxt IAM will automatically refresh your tokens if it detects that your access token has expired, and that your refresh token is not expired. When using a browser, you really don't have to concern yourself with tokens.

Detecting stolen refresh tokens

Nuxt IAM keeps track of expired refresh tokens. Let's say you you have a one refresh token in the database. If you refresh your tokens, you get a new set of tokens, and the old refresh token will be deactivated. If you or someone else steals the old refresh token and attempts to get a new set of tokens using that refresh token, all your refresh tokens will be deactivated, and you will have to login after your access token expires. This feature protects your account against stolen tokens.

Sessions

Nuxt IAM uses sessions to manage user sessions. Every user can only have one session at a time.

© 2022 My Company, Inc