saasmvp OAuth

Appearance

User Authentication ​

The nuxt-saasmvp-oauth module can be used for either or both User and REST API Endpoint authentication. User authentication is implemented using client functions, client middleware and associated REST API endpoints.

READ THIS FIRST

Be sure to review the steps required to initialize the nuxt-saasmvp-oauth module before proceeding.

​

Client Functions ​

smvpGetLoginStatus ​

smvpGetLoginStatus is a client function that returns the Login status of the User.

Type ​

ts
smvpGetLoginStatus():Promise<boolean>

Parameters ​

Parameters: NONE
 
Description: Checks if the User's JWT Access Token is valid (issued and not expired). Returns TRUE if the JWT Access Token is valid, otherwise returns FALSE.

Examples ​

ts
const getLoginStatus = async () => {
  if (await smvpGetLoginStatus()) {
    //user is logged in
  } else {
    //user is NOT looged in
  }
};

smvpGetOAuthToken
​

smvpGetOAuthToken is a client function that sends an Implicit Authorization Grant to the Authorization Server REST API Endpoint smvp-user-token.post.ts. The smvp-user-token.post.ts REST API returns a JWT Access Token and Status code to smvpGetOAuthToken in a JSON object. If a JWT Access Token has been successfully generated by the Authorization Server, the JWT Access Token will be returned to smvpGetOAuthToken with the Status code = 200, otherwise the JWT Access Token returned will be NULL and the Status code = 400. The lifetime of the JWT Access Token is defined by the JWTKeyExpires parameter passed to the smvpInitAuth function. The default is 3600 seconds (1 hour).

Type ​

ts
smvpGetOAuthToken(username: string, password: string):Promise<number>

Parameters ​

Parameter: username
 
Type: String, required
 
Description: The username for the Implicit Authorization Grant.

​

Parameter: password
 
Type: String, required
 
Description: The password for the Implicit Authorization Grant.

Examples ​

ts
const testLogin = async () => {
  //hardcoded data to simulate database
  const username = "rickyg";
  const password = "example";
  const isUserInDatabase = true;

  //add your code to check if username, password in database
  //simulated success for testing
  if (isUserInDatabase) {
    if ((await smvpGetOAuthToken(username, password)) == 200) {
      msg.value = "Login Successful";
    } else {
      msg.value = "Login Error";
    }
    getLoginStatus()
  }
};

smvpGetOAuthAuthorization ​

smvpGetOAuthAuthorization is a client function that sends the JWT Access Token from the nuxt-sassmvp-oauth module useAuth composable to the OAuth Authorization Server's smvp-authorize.post.ts REST API Endpoint for validation. The JWT Access Token is sent from smvpGetOAuthAuthorization to smvp-authorize.post.ts in the X-TOKEN HTTP Header. If the JWT Access Token is validated, a HTTP status 200 is sent in the response from the REST API Endpoint, otherwise if the JWT Access Token is not found in the X-TOKEN HTTP Header OR the JWT Access Token has expired, a HTTP status 400 is returned by the REST API Endpoint.

Type ​

ts
smvpGetOAuthAuhtorization():Promise<number>

Parameters ​

Parameters: NONE
 
Description: Checks if the User's JWT Access Token is valid (issued and not expired). Returns a HTTP status 200 if the JWT Access Token is valid, otherwise returns a HTTP status 400.

Examples ​

The following example is somewhat redundant because you should only need the client function smvpGetOAuthToken when initially requesting and receiving a JWT Access Token. The use of the client function smvpGetOAuthAuthorization performs an immediate validation of the JWT Access Token just issued by smvpGetOAuthToken. This is a good example for testing and exploring the capabilities of the nuxt-saasmvp-oauth module.

ts
const testLogin = async () => {
  //hardcoded data to simulate database access
  const username = "rickyg";
  const password = "example";
  const isUserInDatabase = true;

  //add your code to check if username, password in database
  //NOTE: simulated success for testing ONLY
  if (isUserInDatabase) {
    if ((await smvpGetOAuthToken(username, password)) == 200) {
      if (await smvpGetOAuthAuthorization() == 200) {
        //Login Successful
      } else {
        //Login Error
      }
    }
  }
};

smvpLogout ​

smvpLogout is a client function that invalidates the JWT Access Token on Logout using the nuxt-saasmvp-oauth module useAuth composable and sets the login status to FALSE.

Type ​

ts
smvpLogout():Promise<boolean>

Parameters ​

Parameters: NONE
 
Description: Invalidates the User's JWT Access Token by setting the Token to NULL and login status to FALSE in the `useAuth` composable. Returns TRUE.

Examples ​

ts
const testLogout = () => {
  if (smvpLogout()) {
    //user is logged out
  } else {
    // error
  }
};

​

Client Middleware ​

smvp-pageauth.ts
​

The nuxt-saasmvp-oauth module uses the smvp-pageauth.ts named route middleware defined in the Nuxt definePageMeta compiler macro to check if a page protected by the middleware should be navigated to. The middleware calls smvpGetOAuthAuthorization on each page navigation to determined if the User's JWT Access Token is valid. If the JWT Access Token is valid, page navigation proceeds normally. Otherwise, the User is redirected to the page defined in the smvpInitAuth client function's redirectRoute configuration parameter.

NOTE: Each page you need to protect against unauthorized access needs to have the definePageMeta compiler macro as shown in the example below in the <script> section of the page.

Examples ​

ts
<script setup lang="ts">
definePageMeta({
  middleware: ["smvp-pageauth"],
});
</script>

​

Authorization Server REST API ​

The nuxt-saasmvp-oauth module contains an Authorization Server that has two REST API Endpoints: smvp-user-token.post.ts and smvp-authorize.post.ts which work together to configure the Authorization Server to issue and validate JWT Access Tokens.

smvp-user-token.post.ts
​

The nuxt-saasmvp-oauth module smvpGetOAuthToken client function sends an Implicit Authentication Grant request to the smvp-user-token.post.ts REST API Endpoint to get a JWT Access Token. The Developer should never message this REST API Endpoint directly and is shown for educational purposes only.

JSON Implicit Authorization Grant Request ​

json
{ 
  "iss": "saasmvp", 
  "sub": "user-token", 
  "jti": null, 
  "username": "rickyg", 
  "password": "example", 
  "ts": 1704401038
}

Parameters ​

Parameter: iss
 
Type: String, required, read-only
 
Description: JWT issuer claim. Hardcoded by the `smvpGetOAuthToken` client function.

​

Parameter: sub
 
Type: String, required, read-only
 
Description: JWT subject claim. Hardcoded by the `smvpGetOAuthToken` client function.

​

Parameter: jti
 
Type: String, required, read-only
 
Description: JWT ID. Reserved for future use. Hardcoded by the `smvpGetOAuthToken` client function.

​

Parameter: username
 
Type: String, required
 
Description: The username for the Implicit Authorization Grant. A parameter supplied to the `smvpGetOAuthToken` client function by the Developer.

​

Parameter: password
 
Type: String, required
 
Description: The password for the Implicit Authorization Grant. A parameter supplied to the `smvpGetOAuthToken` client function by the Developer.

​

Parameter: ts
 
Type: Number, required
 
Description: The current Unix Epoch time for the Implicit Authorization Grant. Hardcoded by the `smvpGetOAuthToken` client function.

​

cURL Example ​

sh
curl --location 'http://localhost:3000/api/smvp/smvp-user-token' \
--header 'Content-Type: application/json' \
--data '{ 
  "iss": "saasmvp", 
  "sub": "user-token", 
  "jti": null, 
  "username": "rickyg", 
  "password": "example", 
  "ts": 1704401038
}'

Valid JSON Response ​

json
{
  "message": "JWT User Token Generated",
  "status": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzYWFzbXZwIiwic3ViIjoidXNlci10b2tlbiIsImp0aSI6bnVsbCwidXNlcm5hbWUiOiJyaWNreWciLCJwYXNzd29yZCI6ImV4YW1wbGUiLCJ0cyI6MTcxNjMzMDA4MCwiaWF0IjoxNzE2MzMwMDgwLCJleHAiOjE3MTYzMzcyODB9.97g1mSb_x00T3AnwjcOpDSzTC6ClilZvys8Gez7Wi8Y"
  }
}

Error JSON Response ​

json
{
  "message": "JWT User Token Not Generated",
  "status": 400,
  "data": {
    "token": null
  }
}

smvp-authorize.post.ts
​

The nuxt-saasmvp-oauth module smvpGetOAuthAuthorization and smvpGetLoginStatus client functions send a JWT Access Token in the HTTP X-TOKEN Header to the smvp-authorize.post.ts REST API Endpoint to validate a JWT Access Token. The Developer should never message this REST API Endpoint directly and is shown for educational purposes only.

cURL Example ​

sh
curl --location --request POST 'http://localhost:3000/api/smvp/smvp-authorize' \
--header 'Content-Type: application/json' \
--header 'X-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzYWFzbXZwIiwic3ViIjoidXNlci10b2tlbiIsImp0aSI6bnVsbCwidXNlcm5hbWUiOiJyaWNreWciLCJwYXNzd29yZCI6ImV4YW1wbGUiLCJ0cyI6MTcwNDQwMzk3MiwiaWF0IjoxNzA0NDAzOTcyLCJleHAiOjE3MDQ0MTExNzJ9.rLroosDA-XlinviRPZCzssNJiqu73-ydqAj_e0aAKS0'

Valid JSON Response ​

json
{
  "message": "saasmvp OAUTH smvp-authorize.posts.ts: AUTHORIZED",
  "status": 200,
  "data": {}
}

Error JSON Response ​

json
{
  "message": "saasmvp OAUTH smvp-authorize.posts.ts: JWT Token Expired",
  "status": 400,
  "data": {}
}

Released under the MIT License

Copyright © 2024 The saasmvp Project