Why does this happen? The authentication worked, the session is valid, the user is authenticated, but the authorization failed.

This specific issue is called IDOR (Insecure Direct Object Reference). It’s one of the most common security bugs and is categorized under Broken Object Level Authorization (BOLA) in the OWASP API Security Top 10.

In this tutorial, you’ll learn:

• Why IDOR happens

• Why authentication alone is not enough

• How object-level authorization works

• How to fix IDOR properly in Next.js API routes

• How to design safer APIs from the start

Table of Content

• Table of Content

• Authentication vs. Authorization

• What is an IDOR Vulnerability?

• The Vulnerable Pattern in Next.js

• How to Handle IDOR in Next.js

  • Object-Level Authorization

• How to Design Safer Endpoints (/api/me)

• Mental Model for API Design

• Conclusion

Authentication vs. Authorization

Before writing further, let’s clarify something critical.

• Authentication answers: Who are you?

• Authorization answers: What are you allowed to access?

In IDOR scenarios, authentication works (the user is logged in), while authorization is missing or incomplete. That distinction is the core lesson of this article.

What is an IDOR Vulnerability?

An IDOR vulnerability happens when your API fetches a resource by an identifier (like a user ID), and then you do not verify that the requester owns or is allowed to access that resource.

Example of such a request:

GET /api/users/123

The code above is an HTTP GET request to the /api/users/123 route. The GET method is used to request data from the server. This indicates that the client is requesting a specific user with the ID 123 and this request returns the user data in a response (often in JSON format).

If your backend makes the request using a similar structure to the code snippet below without checking who is making the request, you have an IDOR vulnerability, even if the user is logged in.

db.user.findUnique({ where: { id: "123" } })

What the code does is to query the database for a single user record. The db.user part refers to the user model/table and findUnique() is a method that returns only one record based on a unique field. Inside the method, the where clause specifies the filter condition and { id: "123" } tells the database to find the user whose unique id equals "123". If a matching record exists, it returns that user object; otherwise, it returns null.

The Vulnerable Pattern in Next.js

Looking at this Next.js App Router API route:

// app/api/users/[id]/route.ts
import { NextResponse } from "next/server";
import { db } from "@/lib/db";

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

Before going to the implication of this code snippet, let's understand what the code does. It defines a dynamic API route for /api/users/[id]. The exported GET function is an async route handler that runs when a GET request is made to this endpoint. It receives the request object and a params object, where params.id contains the dynamic [id] in the URL segment. The db.user.findUnique() method queries the database for a user whose id matches params.id, and the select option limits the returned fields to id, email, and name. Finally, NextResponse.json() sends the retrieved user data back to the client as a JSON response.

Now, to the implication, the code is a bad approach because the route accepts a user ID from the URL, fetches that user directly from the database, and returns the result. There is no session validation, no ownership check, and no role check.

If a logged-in user changes the id in the URL, they may access other users’ data. This is simply IDOR.

How to Handle IDOR in Next.js

The first element of defense is verifying identity. We’ll use getServerSession from NextAuth (adjust if using another auth provider). This change ensures that you read the session from the cookies, verify it on the server side, and ensure the user has a valid ID. This prevents unauthenticated access.

// lib/auth.ts
import { getServerSession } from "next-auth";
import { authOptions } from "@/lib/authOptions";

export async function requireSession() {
  const session = await getServerSession(authOptions);

  if (!session?.user?.id) {
    return null;
  }

  return session;
}

The code above defines an authentication helper function called requireSession. The getServerSession(authOptions) function retrieves the current user session on the server using the provided authentication configuration. The optional chaining (session?.user?.id) in the if block that follows safely checks whether a logged-in user and their id exist. If no valid session or user ID is found, the function returns null, indicating the request is unauthenticated. Otherwise, it returns the full session object so it can be used in protected routes or server logic.

You have successfully confirmed that the user and session exist; now, update the route:

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

The fix is incomplete yet, but in the above code, you’ve prevented anonymous access. The GET handler calls the requireSession() that was created earlier to verify that the request is authenticated. If no valid session is returned, it immediately responds with a JSON error message and a 401 Unauthorized HTTP status. If the user is authenticated, it proceeds to call db.user.findUnique() to fetch the user whose id matches params.id, selecting only the id, email, and name fields. Finally, it returns the retrieved user data as a JSON response using NextResponse.json().

Something is still missing. Can you guess? Any authenticated user can still request any resource by changing the URL path to the request they want. How? This leads us to object-level authorization.

Object-Level Authorization

An object-level authorization ensures that a user can only access their own data (unless explicitly permitted).

The improvement to the code would be to add an ownership check. The adjustment ensures the API request checks if the requester is authenticated and owns the requested object. If either fails, access is denied.

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  if (session.user.id !== params.id) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

Let's take a look at what happened in the code, the GET handler first authenticates the request using requireSession(), returning a 401 response if no valid session exists. It then performs an authorization check by comparing session.user.id with params.id. If they do not match, it returns a 403 Forbidden response, preventing users from accessing other users’ data. If both checks pass, it queries the database using db.user.findUnique() to retrieve the specified user and limits the result to selected fields. Finally, it sends the user data back as a JSON response. With this, you’ve enforced an object-level authorization.

How to Design Safer Endpoints (/api/me)

The safest approach in designing your endpoint is to eliminate the risk entirely. Instead of allowing users to specify IDs (/api/users/:id), use /api/me, because the server already knows the user’s identity from the session.

// app/api/me/route.ts
export async function GET() {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: session.user.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

This approach makes sure that your API only returns data for the currently authenticated user. It first calls requireSession() to ensure the request is authenticated, returning a 401 response if no session exists. Instead of using a URL parameter, it reads the user’s ID directly from session.user.id, ensuring the user can only access their own data. It then calls db.user.findUnique() to retrieve that user from the database, selecting only specific fields, and returns the result as a JSON response.

You can be confident with this approach because the client cannot manipulate user IDs. The server gets the user identity from a trusted source, and the attack surface is reduced. This is called secure-by-design API model.

Now, you should clearly understand that authentication does not imply authorization. Hence,

• IDOR occurs when object ownership is not verified

• Every API route that accepts an ID must validate access

• Safer API design reduces vulnerability surface

• Authorization must always run on the server

Mental Model for API Design

When writing any API route, answer these questions:

1. Who is making this request?

2. What object are they requesting?

3. Does policy allow them to access it?

If you cannot clearly answer all three, your route may be vulnerable.

Conclusion

IDOR vulnerabilities happen when APIs trust user-supplied identifiers without verifying ownership or permission.

To prevent them in Next.js, authenticate every private route, enforce object-level authorization, centralize authorization logic, and write tests for forbidden access.

Security is not about adding logins, it’s about enforcing security policy on every object access.

In this article, you'll learn about:

• What a JSON Web Token (JWT) is

• How JWTs are structured and created

• Different JWT signing techniques and algorithms (Symmetric vs. Asymmetric)

• How JWTs are used in real-world authentication flows

• Important security best practices for using JWTs

Table of Contents

• What is a JWT?

  • JSON Web Tokens Are Made Of Three Elements

  • Asymmetric Signing (RS256) Explained

  • Analogy: The Lock and Key for Asymmetric Signatures

• Symmetric Signing: HS256 (HMAC with SHA-256)

  • How HS256 Verification Works

• JWTs in Action: A Typical Authentication Flow

• JWT Security Best Practices & Considerations

What Is a JWT?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
— Introduction to JWT by jwt.io

While accurate, this definition can be a bit dense at first glance. Imagine you want to send someone a sealed, tamper-proof message. That's essentially what a JSON Web Token (JWT) is. It's a secure message, a special kind of message designed to be sent between two parties which can be assured it came from an expected sender.

Each JWT is digitally signed using either a secret code (for symmetric algorithms like HMAC) or a private key (for asymmetric algorithms like RSA or ECDSA).

This secret code or private key is known only to the system that issues the JWT (often called an authentication provider, like Auth0, AWS Cognito, or Firebase Auth, which handles user logins and identity).

This signature proves two things:

1. Authenticity: It proves the message really came from who it claims to be from.

2. Integrity: It proves that the message hasn't been changed or tampered with since it was signed. If even one character is altered, the signature won't match, and you'll know something is wrong, meaning the contents of the JWT can't be trusted.

JSON Web Tokens Are Made of Three Elements

JWTs are made up of 3 key parts:

1. Header

2. Payload

3. Signature

Header

The header contains metadata information about the token. Think of it like a label on a package – it tells you what’s inside and how it was prepared.

Typically, the header contains:

alg: This specifies the algorithm used to sign the JWT. Common algorithms are HS256 (HMAC with SHA-256) or RS256 (RSA with SHA-256).

typ: This specifies the type of token, which is almost always JWT for standard JSON Web Tokens.

Example (decoded):

{ 
  "alg": "RS256",
  "typ": "JWT" 
}

Payload

This is the second part of the JWT, and it's where the real data or "claims" are stored. Claims are statements about an entity (usually a user) and any other additional data. Using the previous analogy of a package, think of it as the “contents” of the package.

There are three types of claims:

1. Registered Claims: These are predefined claims that are recommended for common use cases. They are not mandatory but are very useful for interoperability. These include:

• iss – issuer, who issued the token (for example, your application’s domain)

• sub – subject, the subject of the token (for example, a User’s ID)

• aud – audience, the audience of the token (that is, who the token is intended for – for example, a specific API)

• exp – expiration, the expiry date as a timestamp

• iat – issued at, when the token was issued as a timestamp

• nbf – not before, when the token becomes valid (that is, the token cannot be used or deemed valid before this timestamp)

• jti – JWT ID, a unique identifier for the token, useful for preventing replay attacks or blacklisting

2. Public Claims: These can be defined by anyone using JWTs. To avoid naming conflicts, it's a good practice to register them or define them using a unique identifier like a URI.

3. Private Claims: These are custom claims created to share specific information between parties who agree on using them. They are entirely up to you and your application's needs.

Example payload:

{
  "sub": "1234567890", //  subject
  "name": "John Doe", // private claim
  "admin": true, // private claim / role
  "iat": 1678886400, // Issued at a specific timestamp
  "exp": 1678890000  // Expires at a specific timestamp
}

Like the header, this JSON object is also Base64Url encoded (a URL-safe variant of Base64 encoding) to form the second part of the JWT string.

Important Note: The payload is encoded*, not encrypted.* This means that anyone can easily decode the JWT and read its contents. Never put sensitive information (like passwords) directly into the payload unless the entire JWT itself is encrypted (which is a separate process called JWE - JSON Web Encryption). The security of a standard JWT comes entirely from the signature, which prevents tampering.

Signature

The signature, as we've already discussed, is the most important part of the JWT. Without it, there's no protection applied to the JWT, meaning no way to validate the origin of the token or its integrity.

The signature is created by taking the encoded header, the encoded payload, and a secret key (or a private key if using asymmetric algorithms like RSA). These are then run through the cryptographic algorithm specified in the header (alg field). For HS256, a shared secret key is used. For RS256, a private key is used to sign, and a corresponding public key is used to verify. We’ll get on to verification soon.

Think of it like a tamper-proof seal on your package, or even better, a wax seal on a letter. If you receive your letter and the wax seal has been broken, you'd naturally believe the contents of the letter may not be original and therefore can't be trusted.

In pseudo-code it would look like this:

Signature = Algorithm( Base64Url(Header) + "." + Base64Url(Payload), SecretKey )

The result of this signing process is the signature, which is also Base64Url encoded to form the third part of the JWT string.

At the end of the whole process your JWT would look like this:

base64EncodedHeader.base64EncodedPayload.base64EncodedSignature

Asymmetric Signing (RS256) Explained

When a JWT uses an algorithm like RS256 (RSA Signature with SHA-256), it employs an asymmetric cryptographic process involving a public and private key pair. This is where the core magic of proving authenticity and integrity happens without needing to share a secret.

The Signing Process (by the Issuer)

The sender (the server that issues the JWT, like Auth0) possesses the private key. This key is kept absolutely secret and secure. Here are the steps:

1. Prepare the data: The server takes the header (which includes the algorithm) and the payload. It Base64Url-encodes them, and then concatenates them with a dot: Base64Url(Header) + "." + Base64Url(Payload).

   For example, with this header:

    {
      "typ": "JWT",
      "alg": "RS256"
    }
   

   And this payload:

    {
      "sub": "1234567890",
      "name": "John Doe",
      "admin": true,
      "iat": 1751494086,
      "exp": 1751497686
    }
   

   This would create a Base64Url-encoded header.payload string like the animated example below:

   

2. Calculate the hash: It then calculates a hash (using SHA-256 in this case) of this combined header and payload string.

3. Sign the hash: Finally, it signs this hash using its private key. This cryptographically transformed hash is the signature part of the JWT.

The JWT is then formed by concatenating the Base64Url-encoded header, the Base64Url-encoded payload, and the Base64Url-encoded signature, separated by dots: header.payload.signature.

The top segment below shows the full JWT token (header.payload.signature):

The Verification Process

This is where the magic happens, and it's often a point of confusion. The public key doesn't "decrypt" the original data like a symmetric key does. Instead, it performs a unique verification process.

The receiver (the client or another server that needs to verify the JWT) possesses the public key. This key does not need to be kept secret – it can be freely distributed.

Here's a step-by-step explanation:

1. Separate the parts: The first thing the receiver does is split the incoming JWT string into its three Base64Url-encoded components: the Header, the Payload, and the Signature.

2. Obtain the public key: The verifier needs the public key that corresponds to the private key used by the issuer. Public keys are often available via a JWKS (JSON Web Key Set) endpoint (for example, your-domain.com/.well-known/jwks.json).

3. Re-create the data to be hashed: The receiver takes the received, Base64Url-encoded Header and the received, Base64Url-encoded Payload. It then combines them exactly as the issuer did: EncodedHeader.EncodedPayload.

4. Compute a local hash (Hash A): This combined string is then put through the same hashing algorithm (for example, SHA-256) that was specified in the JWT's header. This produces a new, locally computed hash (let's call this "Hash A"). This local hash represents what the content should look like if it hasn't been tampered with.

5. "Unsign" the received signature with the public key to get the original signed hash (Hash B): This is the core cryptographic step. The verifier uses the public key (obtained in step 2) to perform a mathematical operation on the received signature. This operation does not create a new signature for comparison. Instead, it effectively "unsigns" or "decrypts" the signature to reveal the original hash ("Hash B") that was produced by the issuer's private key.

   • Crucial Point: This process is for verifying authenticity, not decrypting confidential data. The public key confirms that the signature was indeed created by the corresponding private key, and as part of that confirmation, it returns the original hash that was signed.

6. Compare the hashes: The verifier now has two hashes:

   • Hash A: The hash it computed locally from the received header and payload (from step 4).

   • Hash B: The original hash that was extracted from the received Signature using the public key (from step 5)

7. If Hash A matches Hash B: It proves two critical things:

   1. Authenticity: The token was indeed signed by the legitimate holder of the corresponding private key (for example, Auth0).

   2. Integrity: The content of the header and payload has not been tampered with since it was originally signed. If even a single character in the header or payload were changed, Hash A would be different, and it would not match Hash B. In this case, the JWT is considered valid and its contents can be trusted.

8. If the hashes do NOT match: The token is considered invalid and must be rejected. This indicates either that the JWT was signed by an unauthorised party (a forged token) or that its header or payload has been altered after it was signed.

Analogy: The Lock and Key for Asymmetric Signatures

Private Key: A special, unique key that can lock a box (create a signature). Only the owner has this key.

Public Key: A widely distributed key that can test if a box was locked by the corresponding private key. It can't lock a new box, but it can confirm if an existing lock is authentic.

You don't re-lock the box with the public key. You use the public key to check if the existing lock (the signature) is genuine and corresponds to the contents of the box.

Symmetric Signing: HS256 (HMAC With SHA-256)

While RS256 uses a pair of keys (private for signing, public for verifying), many JWTs you'll encounter are signed symmetrically, most commonly with the HS256 algorithm. HS256 stands for HMAC (Hash-based Message Authentication Code) with SHA-256.

The fundamental difference here is the use of a single, shared secret key for both signing and verification.

How HS256 Signing Works

1. Shared secret key: The issuer (for example, your authentication provider) possesses a single, confidential secret key. This key is known only to the issuer and any parties (like your API) that need to verify the token.

2. Combine header and payload: Just like with asymmetric signing, the issuer takes the Base64Url-encoded Header (which specifies "alg": "HS256") and the Base64Url-encoded Payload, and joins them with a dot.

3. Apply HMAC-SHA256: This combined string is then fed into the HMAC-SHA256 algorithm along with the secret key. The HMAC algorithm uses the secret key to create a unique hash (the signature) of the data. In pseudo-code, it looks like this:

   Signature = HMAC-SHA256( Base64Url(Header) + "." + Base64Url(Payload), SecretKey )

4. Form the JWT: The resulting signature (which is also Base64Url-encoded) is appended to the header and payload with a dot, forming the complete JWT: base64EncodedHeader.base64EncodedPayload.base64EncodedSignature.

How HS256 Verification Works

When a receiver gets an HS256-signed JWT, it goes through a verification process.

First, it separates the parts. The JWT is split into its three Base64Url-encoded components: Header, Payload, and Signature, as we did with asymmetric JWTs.

Then, it obtains the shared secret key. The receiver must also possess the exact same secret key that the issuer used to sign the token. This key is not publicly distributed like a public key – it must be securely provisioned to any entity that needs to verify tokens.

Next, it re-calculates the signature. The receiver does this by taking the received Base64Url-encoded Header and Payload, combining them, and then re-applying the HMAC-SHA256 algorithm using the same secret key. This produces a new, locally computed signature.

Finally, the receiver compares the signature it just calculated locally with the signature it received as part of the JWT.

• If the two signatures match: The token is considered valid. This confirms its authenticity (it came from someone who knows the secret) and integrity (it hasn't been tampered with).

• If the signatures do NOT match: The token is invalid and must be rejected. This indicates either tampering or that it was signed with a different, unknown secret key.

Key Differences and Considerations:

• Key management: With HS256, the secret key must be securely shared and kept confidential by all parties involved in both signing and verifying. This can be more challenging to manage securely at scale compared to the public/private key model, where only the private key needs strict secrecy.

• Performance: HS256 is generally faster to compute than asymmetric algorithms like RS256, making it suitable for high-volume scenarios where the secret key can be securely distributed.

JWTs in Action: A Typical Authentication Flow

Now that you understand how JWTs are structured and signed, let's look at how they're typically used in a real-world web application. This authentication flow is a common pattern you'd encounter.

Step 1: User Logs In:

A user opens a client application (for example, a web browser, mobile app) and enters their login credentials (username and password).

The client sends these credentials securely (always over HTTPS!) to an authentication server (like Auth0, AWS Cognito, or your own backend's authentication endpoint).

Step 2: Authentication Server Issues JWT:

Then the authentication server verifies the user's credentials. If valid, it generates a new JWT. This JWT contains claims (like the user's ID, roles, expiration time) in its payload and is digitally signed by the server's private key (for asymmetric algorithms like RS256) or secret key (for symmetric algorithms like HS256).

The server then sends this signed JWT back to the client.

Step 3: Client Stores JWT:

The client receives the JWT and typically stores it in a secure location, such as browser memory storage, session storage, or an HTTP-only cookie. The method of storage depends on the client type and security considerations.

Step 4: Client Makes API Calls:

When the user wants to access a protected resource on a backend API (for example, their profile data, a private feed), the client includes the JWT in the request.

The standard way to do this is by sending the token in the Authorization header of the HTTP request, prefixed with the word Bearer:

Authorization: Bearer <your_jwt_here>

Step 5: API Verifies JWT & Authorises Request:

Now, the backend API receives the request and extracts the JWT from the Authorization header. The API then performs the JWT verification process depending on the algorithm:

• It checks the token's claims, especially the exp (expiration) claim, to ensure it's still valid.

• If the token is valid, the API trusts the claims within the payload (for example, the user's ID) and proceeds to fulfill the request, potentially using the user's roles to determine if they have permission to access the requested resource.

• If the token is invalid (bad signature, expired, and so on), the API rejects the request, typically with an HTTP 401 Unauthorised status.

This flow is powerful because JWTs are stateless: once issued, the authentication server doesn't need to keep a record of active sessions. The API can verify the token independently, which simplifies scaling and reduces server load.

JWT Security Best Practices and Considerations

While JWTs offer powerful authentication capabilities, using them securely requires careful attention to best practices. Misconfigurations or oversight can lead to significant vulnerabilities.

Always Use HTTPS/TLS:

Crucial: JWTs are encoded, not encrypted, by default. This means anyone who intercepts the token during transmission can easily read its payload. Therefore, JWTs (and all authentication traffic) must always be transmitted over HTTPS (TLS) to encrypt the communication channel itself and prevent eavesdropping.

Protect Your Signing Keys:

Whether it's a private key (for RS256) or a shared secret key (for HS256), these keys are paramount. If an attacker gains access to your signing key, they can forge valid JWTs, impersonate users, and compromise your system. Store these keys securely, preferably in dedicated key management services.

Keep Access Tokens Short-Lived (exp claim):

You should always set short expiration times (for example, 5-15 minutes) for your JWTs used as access tokens. This minimises the window of opportunity for an attacker if a token is compromised.

Since JWTs are stateless, they are hard to revoke immediately once issued. A short lifespan is your primary defense against compromised tokens.

Implement Refresh Tokens (for Longer Sessions):

To maintain user experience with short-lived access tokens, use refresh tokens. A refresh token is a separate, longer-lived token (usually stored more securely) that can be exchanged for a new, short-lived access token when the current one expires, without requiring the user to re-authenticate. Refresh tokens can be revoked by the server, offering better control.

Never Put Sensitive Data in the Payload:

Reiterating this crucial point: the JWT payload is Base64Url encoded, which is easily reversible. Do not put passwords, highly sensitive PII (Personally Identifiable Information), or confidential business data directly into the JWT payload. Only include non-sensitive or publicly available information, or data that's already encrypted by other means.

Validate ALL Claims on Verification:

When verifying a JWT, don't just check the signature. Always validate all relevant claims, including:

• exp (Expiration): Ensure the token hasn't expired.

• iss (Issuer): Verify the token came from the expected authentication server.

• aud (Audience): Ensure the token is intended for your specific API/application.

• nbf (Not Before): Check if the token is active yet.

Consider Token Revocation (for critical cases):

For situations requiring immediate revocation (for example, user password change, account deactivation), typical stateless JWTs are challenging. Strategies include:

• Short expiration times (as above).

• A blacklist/revocation list: Store the jti (JWT ID) of revoked tokens in a database, checking this list on every request. This adds a stateful lookup but provides immediate revocation.

Thanks for reading!

I hope you’ve found this tutorial useful, and as always if you want to ask any questions or hear about upcoming articles, you can always follow me on ‘X’, my handle is @grantdotdev and follow by clicking here.

In this article, you’ll learn how to integrate this type of authorization with Permit.io in Nuxt.

Table of Contents

• Table of Contents

• What is the Difference Between Authentication and Authorization?

• What is Role Based Access Control (RBAC)?

• What are the Benefits of Using Authorization As A Service?

• What We’ll Be Building

• How to Plan RBAC with Permit.io

• How to Setup Permit.io in Nuxt

• How to Control API Access with Nuxt Middleware

• How to Test RBAC in the Community Dashboard

• Summary

What is the Difference Between Authentication and Authorization?

When building applications, we often carry out authentication together with authorization. However, these two concepts are essentially different.

Authentication is verifying who a user is. During the authentication process, the user usually needs to log in with some identifier like email, phone, username, with Google, with Microsoft, and so on.

Authorization specifies the resources an authenticated user can view and what they can do in the application. Authorization tells a user's access rights after that user has been successfully authenticated.

For example, authentication is a user logging in with email and password or verifying their phone number with SMS. On the other hand, authorization is a writer creating and editing posts while only admins can approve and publish those posts.

The primary purpose of authentication is to establish a user's identity before granting them access to the system. The main goal of authorization is to control user actions and protect sensitive data or resources.

What is Role Based Access Control (RBAC)?

Role-Based Access Control (RBAC) is an authorization model that you can use to manage and restrict access to system resources. It is based on the responsibilities, duties, or roles of users.

In RBAC, roles represent predefined sets of permissions that tell which actions a user can execute in an application. These roles are then assigned to users based on their job functions or responsibilities.

In common systems, anyone can assign permissions to individual users. In RBAC, we group permissions into roles. In turn, we assign these roles to users. For example, in a community dashboard, users might have roles like “Admin”, “Mentor”, or “Member”.

Aside from Role-Based Access Control, other popular authorization models exist such as Attribute-Based (ABAC) and Relationship-based (ReBAC) access controls. Attribute-Based Access Control uses a wide range of attributes and fits constantly changing systems. You could also combine it with Role-Based Access Control. For more info, see the Permit.io article on RBAC vs. ABAC.

What are the Benefits of Using Authorization As A Service?

You can build authorization models yourself in your application. But it may be time-consuming and cost-ineffective in the long run.

Using an external provider for authorization allows you to focus on the business logic in your applications. The benefits of outsourcing authorization are similar to using a third party like Auth0 or Firebase for Authentication.

Authorization as a Service provides a solution for managing user access and permissions in applications. When you use such an authorization solution, you enjoy enhanced security, granular access policies’ control, auto-scaling policies, reduced maintenance burden, faster upgrades, robust logging, and so on.

Permit.io is free to use for up to a 1000 Monthly Active Users, and has a UI and API for RBAC, ABAC, and ReBAC.

To Get Started with Permit.io:

• Go to app.permit.io

• Create an account

• Create a workspace (in your account)

What We’ll Be Building

A community dashboard connects members within a community or forum. It is a platform where they can interact and access resources.

For demo purposes of RBAC, we’ll build a simple community dashboard that will include 3 types of content (entities): posts, materials, and announcements.

The code we will be using is at https://github.com/obumnwabude/rbac-community-dashboard. It consists of a Nuxt repo with its server configured for API calls and its front end built with Vue. Clone it with git and explore the code in an editor/IDE.

In the server, we will expose GET, POST, and DELETE endpoints for each entity (posts, materials, and announcements). In Nuxt, you can use the HTTP verb in the file name for the endpoint handler. So we can have posts.get.ts*, posts.delete.ts, materials.post.ts,* and so on, with each file containing the respective handler for the involved API endpoint.

In addition, the server files store and retrieve entities from JSON files. You should have a robust database setup in your product. For this project, we’ll use local JSON files to build a minimum reproducible example with focus on roles and authorization.

In the front end, we have four pages: three for the entities and a settings page. There is also a simple navigation: a bottom bar on smaller screens and a sidebar on wider ones. Each entity page shows a list of its items and a small form to create new ones.

Furthermore, the demo code uses tailwindcss to style everything quickly. The settings page contains hardcoded user examples and roles for the demo. When testing, toggle the current user and see the roles in action.

This article focuses on the parts of the code that deal with authorization. For the backend and the UI specifics of the community dashboard, we will only overview them. After that, we will deep dive into RBAC touchpoints.

How to Plan RBAC with Permit.io

Overall, planning authorization means mapping out “who” can carry out an action on “what”. In RBAC, we define roles and then assign them to users. The roles and users combo is the “who” part of the authorization.

The “what” side refers to the entities or resources that your application provides or manages. For this article’s example, we’ve chosen our resources as Posts, Materials, and Announcements.

Actions are user activity. The most common actions are “create”, “read”, “update”, and, “delete”. Per resource in your application, you can use these four actions, add more, or omit some. In this article, our resources will each have all four actions.

When planning authorization, define resources alongside the “actions” users can execute on each resource. After that, define roles. For each role, specify what actions a user holding that role can carry out on each resource. The mapping of resources, actions, and roles allows you to define the authorization policies of your application.

Permit.io makes it easy to edit policies. In Permit.io, you have an intuitive dashboard where you can create resources and their actions, create roles, and merge both with policy tables.

For our Community Dashboard example, we will create three roles with incremental access: member, mentor, and admin. For each role, we’ll allow read access to all resources. However, each role has different management access levels to the resources as follows:

• Members can view all entities but can only create or delete posts.

• Mentors can view all entities and can create or delete posts and materials.

• Admins can create, view, and delete all entities.

Assigning roles to actions in resources is the same as editing policies.

How to Setup Permit.io in Nuxt

For our demo project, you need to run npm install, create a .env file, and export your Permit token.

However, if you are building a new project, to setup Permit in Nuxt, first install it with npm.

npm install permitio

After that, create a .env file and add your PERMIT_TOKEN. Get the token from the dashboard.

PERMIT_TOKEN=permit_key_XXXXXXXXXXXXXXXXXXXXX

To make this token available to the Nuxt runtimeConfig, add it to the nuxt.config.ts file. Also, add permitio (alongside other dependencies) in the transpile array of the build property of the Nuxt config file.

This addition is to account for Nuxt’s specific optimizations. Your nuxt.config.ts file should look like the following:

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  // ... other properties

  build: {
    transpile: ['axios', 'permitio', 'pino']
  },
  runtimeConfig: {
    permitToken: process.env.PERMIT_TOKEN
  }
});

After these, Permit.io should be available to your server code in Nuxt. You can now use in it middleware code to check for permissions.

How to Control API Access with Nuxt Middleware

In simple terms, middleware is code that runs before a target handler. In Nuxt, you can add middleware for API endpoints by creating necessary files in a middleware directory contained in the top-level server directory.

Since we are dealing with permissions, we will name our middleware file permissions.ts. Here, you’ll check if a user is permitted to take an action on a given resource.

Permit.io makes this easy with a simple .check method that returns a Boolean indicating if the user is permitted.

await permit.check(user, action, resource);

For this simple example community dashboard, our middleware code will first try to determine the user and action from the request properties. The example code achieves that in crude ways. They are enough to explain the concept and you should use more robust industry-standard methods for this.

After that, in the example code below, we construct the Permit object using our permit token and the default public PDP (Policy-Decision-Point microservice)’s endpoint. The Permit PDP is open-source. If you wish, you can set up your local/personal PDP by following the steps here.

import { Permit } from 'permitio';

export default defineEventHandler(async (event) => {
  // Only check permissions if the request is a POST or DELETE request
  const { method, path } = event;
  if (method !== 'POST' && method !== 'DELETE') return;

  // Ensure authorization header is present
  let authorization = event.node.req.headers['authorization'];
  if (!authorization) throw new Error('Unauthorized');

  // Extract the user from the authorization header. This is for example
  // purposes only. In a real application, you would use a JWT library or
  // better authentication methods in your API.
  const user = authorization.split(' ')[1];
  if (!user) throw new Error('Unauthorized');

  // Extract the resource from the path. This is for example purposes only.
  let resource = path.split('/').reverse()[0]; // get the last part of the path
  resource = resource.slice(0, -1); // remove the trailing 's' 
  // Capitalize the first letter
  resource = resource.charAt(0).toUpperCase() + resource.slice(1);

  // Set the action on the resource from the request method. 
  // This is for example purposes only. In a real application, you would
  // have a more robust way to determine the action. 
  const action = method === 'POST' ? 'create' : 'delete';

  // Construct the Permit object. Use the token from runtime config.
  const config = useRuntimeConfig(event);
  const permit = new Permit({
    pdp: 'https://cloudpdp.api.permit.io',
    token: config.permitToken
  });

  // Check if the user is permitted to create the resource. 
  // If not, throw an error.
  const isPermitted = await permit.check(user, action, resource);
  if (!isPermitted) throw new Error('Unauthorized');
});

As you can see, if the Permit checker fails, an error will be thrown. This will make Nuxt to prevent unauthorized resource management in your system. Such separation of concerns is efficient, especially in Authorization.

How to Test RBAC in the Community Dashboard

The settings page works together with the stores/permissions.ts file to complete the flow in the front end. We hardcoded the roles and the “user IDs” to ease toggling and testing. You definitely won’t have this in a production application. You can integrate CASL for permission checks in a frontend.

In this demo community dashboard, the UI touchpoints only allow edits of entities for which the acting user has the right roles. In other words, you can only add or delete an entity if the current role in the settings page allows that. Let’s see this in action.

In the Permit.io dashboard, create three test users: “example-member”, “example-mentor”, and “example-admin”. Assign the respective roles to each user.

Start up the Nuxt app by running npm run dev. Visit localhost:3000 in your browser and explore the role-based authorization in the demo community dashboard.

You can see that when you set the Current User to admin, you can create and delete announcements, but when set to guest, you can only view entities and not manage them. With this, we’ve fully implemented authorization.

Summary

You can be more efficient in building your application by focusing on business logic and outsourcing crucial parts like authorization.

In this article, you learned how you can use an authorization solution (Permit.io) to implement Role-Based Access Control in a demo community dashboard with Nuxt. You can also use Permit in any other kind of application (not just community dashboards).

When planning authorization, define resources alongside the “actions” users can execute on each resource. After that, define roles as the permissions the users can have.

Cheers!

FGA allows you to set up detailed access controls that specify who can do what and under which conditions.

In this tutorial, you will learn how to implement fine-grained authorization in Java and Spring Boot using Permit.io.

Here is the source code (remember to give it a star ⭐).

I hope you enjoyed my previous blog about building a custom video conferencing app with Stream and Next.js. These blogs reflect my journey in creating DevTools Academy, a platform designed to help developers discover amazing developer tools.

This tutorial is another effort to introduce you to a super helpful developer tool that I recently explored.

Table of Contents:

• What is Permit?

• Prerequisites

• What is Fine-Grained Authorization?

  • Role-Based Access Control (RBAC)

  • Attribute-Based Access Control (ABAC)

  • Relationship-Based Access Control (ReBAC)

• How to Implement Fine-Grained Authorization

  • Implementing Role-Based Access Control

  • Implementing Attribute-Based Access Control

  • Implementing Relationship-Based Access Control

• How to Implement FGA in Java and SpringBoot

  • Step 1: Setting Up the E-commerce Application

  • Step 2: Get your Environment API Key

  • Step 3: Deploy Policy Decision Point (PDP)

  • Step 4: Running the App

• Next Steps

  • Before We End...

What is Permit?

Permit.io is a full stack, plug-and-play application-level authorization solution that allows you to implement a secure, flexible, authorization layer within minutes, so you can focus on what matters most.

Prerequisites

To fully understand the tutorial, you need to have a basic understanding of Java and Spring Boot. You’ll also need the following:

• Permit.io: A developer tool that simplifies the implementation of FGA.

• Spring Boot Starter Web: Provides essential components for building web applications, including RESTful APIs.

• Gradle: A build tool for managing dependencies.

• JDK 11 or later: The Java Development Kit version required to compile and run your Spring Boot app.

• Postman or cURL: Tools for testing your API endpoints.

What is Fine-Grained Authorization?

Fine-grained authorization offers access control to resources by determining who can access them, to what extent, and under specified conditions.

Contrary to coarse-grained authorization (that handles access based on categories like user roles such as "admin" or "user"), fine-grained authorization gives you the flexibility to define access at a granular level, for specific resources or actions and even attributes.

In Fine Grained Authorization there exist 3 types of policy models for managing authorization; Role Based Access Control (RBAC), Attribute Based Access Control (ABAC), and Relationship-Based Access Control (ReBAC).

Let's take a look, at each of these approaches and see how you can implement them in your application.

Role-Based Access Control (RBAC)

RBAC is a security approach that controls resource access based on the roles of users within an organization. This model streamlines permissions by organizing users into roles and managing access control according to these defined roles.

Key Concepts in RBAC:

Users: People who use the system such as employees or customers.

Roles: A set of permissions or access privileges assigned to a group of users based on their responsibilities or tasks such as admin, manager, or customer.

Permissions: The rights granted to users for interacting with resources, such as read, write, or delete.

Attribute-Based Access Control (ABAC)

ABAC is a versatile and adaptive access control model that decides who can or cannot access resources based on attributes, like user details. The ABAC model allows you to define fine-grained authorization based on user attributes.

Key Concepts in ABAC:

Attributes: Characteristics or properties used to make access control decisions. Attributes are typically categorized into:

• User Attributes: Information about the user (for example, role, department, job title, age, and so on).

• Resource Attributes: Characteristics of the resource (for example, file type, data classification level, creation date, owner).

• Action Attributes: The action the user is trying to perform (for example, read, write, delete, approve).

• Environmental Attributes: Contextual information about the access request (for example, time of day, location, device type, IP address).

Relationship-Based Access Control (ReBAC)

ReBAC is an access control system that grants permissions to access resources based on the relationship between entities within a system. The approach emphasizes defining and managing access control by mapping out how users relate to resources and other entities such as organizations or groups.

Key Concepts of ReBAC:

Entities: Users, resources (such as files and documents), and other entities, such as groups or organizational units.

Relationships: The connections that specify the relationship between two entities. A user might be the "owner" of a document or a "member" of a team, for instance.

Policies: Rules that use relationships to determine access rights. A user can access a resource or execute an action on it if they have a particular relationship with it.

How to Implement Fine-Grained Authorization

Now that you have a basic understanding of RBAC, ABAC, and ReBAC, let’s see how we can implement these models in an e-commerce app.

Implementing Role-Based Access Control

Step 1: Navigate to Permit.io, and then create an account and your workspace.

By default, you should see a project that includes two environments: Development and Production.

Step 2: Create a resource named Products. To create the resource, open the Policy tab on the left sidebar and then open the Resources tab at the top. After that, click the Create a Resource button and then create a resource called Products with actions read, create, update, and delete.

Step 3: Create another resource called Reviews with actions read, create, update, and delete.

Step 4: Open the Policy Editor tab. You’ll see that 3 roles named admin, editor, and viewer were created.

• Role admin has permission to create, delete, read, or update a product or a review.

• Role editor has permission to create, read, or update a product or a review but not delete any.

• Role viewer has permission to create and read a product or a review but not delete or update any.

Implementing Attribute-Based Access Control

Step 1: Open the Resources tab, then click the Add Attributes button.

• Add an attribute called vendor

• Add an attribute called the customer

Step 2: Open the ABAC Rules tab, then create a new ABAC Resource Set called Own Products that depends on the Products resource. After that, add a condition that gives permissions only to the user who created a product based on the vendor attribute.

Step 3: Create another ABAC Resource Set called Own Reviews that depends on the Reviews resource.

Implementing Relationship-Based Access Control

Step 1: Open the Resources tab and edit the Products resource. Add role vendor in the ReBAC options section. Then set products as parent of reviews in the relations section.

Step 2: Edit the Reviews resource by adding role customer in the ReBAC options section, as shown below:

Step 3: Go to Policy Editor tab and add:

• role vendor permission to update and delete own products.

• role customer permission to update and delete their own reviews on products.

How to Implement FGA in Java and SpringBoot

Now that we have defined RBAC, ABAC, and ReBAC policies in the Permit.io web interface, let’s learn how to enforce them in an E-Commerce Management System application using the Permit.io API.

There’s a lot of code coming up, so make sure you read through the extensive comments I’ve left throughout each code block. These will help you understand more fully what’s going on in this code.

Step 1: Setting Up the E-commerce Application

To set up the e-commerce application and git clone the source code.

git clone https://github.com/tyaga001/java-spring-fine-grained-auth.git

Installing Permit package SDK

To install the Permit package SDK, you add the SDK under the dependencies block in the build.graddle file.

## Dependencies

To set up the necessary dependencies for your Spring Boot project, include the following in your `build.gradle` file:

```groovy
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    // Add this line to install the Permit.io Java SDK in your project
    implementation 'io.permit:permit-sdk-java:2.0.0'
}

Initializing the Permit SDK

You can initialize the Permit SDK Client using the code below:

package com.boostmytool.store.config;

import io.permit.sdk.Permit;
import io.permit.sdk.PermitConfig;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration  // Marks this class as a configuration class for Spring IoC
public class PermitClientConfig {

    @Value("${permit.api-key}")  // Inject Permit API key from application properties
    private String apiKey;

    @Value("${permit.pdp-url}")  // Inject Permit PDP (Policy Decision Point) URL from application properties
    private String pdpUrl;

    /**
     * Creates a Permit client bean with custom configuration
     * @return Permit client instance
     */
    @Bean
    public Permit permit() {
        return new Permit(
                new PermitConfig.Builder(apiKey)  // Initialize PermitConfig with API key
                        .withPdpAddress(pdpUrl)   // Set the PDP address
                        .withDebugMode(true)      // Enable debug mode for detailed logging
                        .build()                  // Build the PermitConfig object
        );
    }
}

Syncing Users with SDK

To start enforcing permissions, you should first sync a user to Permit, and then assign them a role.

In the code below, the UserService class provides methods for user login, signup, role assignment, and authorization, with exception handling for possible errors when interacting with the Permit API.

package com.boostmytool.store.service;

import com.boostmytool.store.exception.ForbiddenAccessException;
import com.boostmytool.store.exception.UnauthorizedException;
import io.permit.sdk.Permit;
import io.permit.sdk.api.PermitApiError;
import io.permit.sdk.api.PermitContextError;
import io.permit.sdk.enforcement.Resource;
import io.permit.sdk.enforcement.User;
import org.springframework.stereotype.Service;

import java.io.IOException;

@Service  // Marks this class as a Spring service, making it a candidate for component scanning
public class UserService {
    private final Permit permit;

    // Constructor injection for the Permit SDK
    public UserService(Permit permit) {
        this.permit = permit;
    }

    /**
     * Simulates user login by creating and returning a Permit User object.
     * 
     * @param key User's unique key
     * @return User object
     */
    public Object login(String key) {
        return new User.Builder(key).build();
    }

    /**
     * Handles user signup by creating and syncing a new Permit User.
     * 
     * @param key User's unique key
     * @return Created and synced User object
     */
    public User signup(String key) {
        var user = new User.Builder(key).build();
        try {
            permit.api.users.sync(user);  // Syncs the new user with the Permit service
        } catch (PermitContextError | PermitApiError | IOException e) {
            throw new RuntimeException("Failed to create user", e);  // Handles exceptions during user creation
        }
        return user;
    }

    /**
     * Assigns a role to the user within the "default" environment.
     * 
     * @param user User object to assign the role to
     * @param role Role to be assigned
     */
    public void assignRole(User user, String role) {
        try {
            permit.api.users.assignRole(user.getKey(), role, "default");  // Assigns role in the "default" environment
        } catch (PermitApiError | PermitContextError | IOException e) {
            throw new RuntimeException("Failed to assign role to user", e);  // Handles exceptions during role assignment
        }
    }

    /**
     * Checks if the user is authorized to perform a specific action on a resource.
     * 
     * @param user User object requesting authorization
     * @param action Action to be authorized
     * @param resource Resource on which the action will be performed
     * @throws UnauthorizedException if user is not logged in
     * @throws ForbiddenAccessException if user is denied access
     */
    public void authorize(User user, String action, Resource resource) {
        if (user == null) {
            throw new UnauthorizedException("Not logged in");  // Throws exception if user is not logged in
        }
        try {
            var permitted = permit.check(user, action, resource);  // Performs authorization check
            if (!permitted) {
                throw new ForbiddenAccessException("Access denied");  // Throws exception if access is denied
            }
        } catch (PermitApiError | IOException e) {
            throw new RuntimeException("Failed to authorize user", e);  // Handles exceptions during authorization
        }
    }
}

Then in the code below, the UserController class exposes REST API endpoints for user signup and role assignment. It interacts with the UserService class to handle user-related business logic and provides appropriate HTTP responses.

package com.boostmytool.store.controllers;

import com.boostmytool.store.exception.UnauthorizedException;
import com.boostmytool.store.service.UserService;
import io.permit.sdk.enforcement.User;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController  // Indicates that this class handles HTTP requests and returns JSON responses
@RequestMapping("/api/users")  // Base URL path for all user-related operations
public class UserController {
    private final UserService userService;

    // Constructor injection of UserService, containing business logic for user operations
    public UserController(UserService userService) {
        this.userService = userService;
    }

    /**
     * Handles user signup requests.
     * Endpoint: POST /api/users/signup
     * 
     * @param key Unique key for the new user
     * @return Created User object
     */
    @PostMapping("/signup")
    public User signup(@RequestBody String key) {
        return userService.signup(key);  // Calls the signup method in UserService to create a new user
    }

    /**
     * Handles assigning a role to the logged-in user.
     * Endpoint: POST /api/users/assign-role
     * 
     * @param request HTTP request, used to retrieve the current user
     * @param role Role to be assigned to the current user
     */
    @PostMapping("/assign-role")
    public void assignRole(HttpServletRequest request, @RequestBody String role) {
        // Retrieves the current user from the request attributes
        User currentUser = (User) request.getAttribute("user");

        // Throws an exception if the user is not logged in
        if (currentUser == null) {
            throw new UnauthorizedException("Not logged in");
        }

        // Assigns the specified role to the current user
        userService.assignRole(currentUser, role);
    }
}

Creating RBAC, ABAC, and ReBAC Policy Enforcement Point

In the code below, the ProductService class manages CRUD operations for products and reviews, handling permissions and roles via the Permit API.

Each operation includes user authorization checks, with appropriate exception handling for Permit API errors and resource not found scenarios.

package com.boostmytool.store.service;

import com.boostmytool.store.exception.ResourceNotFoundException;
import com.boostmytool.store.model.Product;
import com.boostmytool.store.model.Review;
import io.permit.sdk.Permit;
import io.permit.sdk.api.PermitApiError;
import io.permit.sdk.api.PermitContextError;
import io.permit.sdk.enforcement.Resource;
import io.permit.sdk.enforcement.User;
import io.permit.sdk.openapi.models.RelationshipTupleCreate;
import io.permit.sdk.openapi.models.ResourceInstanceCreate;
import io.permit.sdk.openapi.models.RoleAssignmentCreate;
import org.springframework.stereotype.Service;

import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;

@Service  // Marks this class as a Spring service
public class ProductService {

    private final List<Product> products = new ArrayList<>();  // In-memory list to store products
    private final AtomicInteger productIdCounter = new AtomicInteger();  // Counter to generate unique product IDs
    private final AtomicInteger reviewIdCounter = new AtomicInteger();   // Counter to generate unique review IDs

    // Builders for Permit resource instances (product and review)
    private final Resource.Builder productResourceBuilder = new Resource.Builder("product");
    private final Resource.Builder reviewResourceBuilder = new Resource.Builder("review");

    private final UserService userService;  // Service for handling user-related operations
    private final Permit permit;  // Permit SDK instance for handling authorization and resource management

    // Constructor for injecting dependencies
    public ProductService(UserService userService, Permit permit) {
        this.userService = userService;
        this.permit = permit;
    }

    // Method to authorize a user for a given action on a resource
    private void authorize(User user, String action, Resource resource) {
        userService.authorize(user, action, resource);
    }

    // Authorizes a user to perform an action on a specific product
    private void authorize(User user, String action, Product product) {
        var attributes = new HashMap<String, Object>();
        attributes.put("vendor", product.getVendor());  // Add vendor attribute to the product
        userService.authorize(user, action, productResourceBuilder.withKey(product.getId().toString()).withAttributes(attributes).build());
    }

    // Authorizes a user to perform an action on a specific review
    private void authorize(User user, String action, Review review) {
        var attributes = new HashMap<String, Object>();
        attributes.put("customer", review.getCustomer());  // Add customer attribute to the review
        userService.authorize(user, action, reviewResourceBuilder.withKey(review.getId().toString()).withAttributes(attributes).build());
    }

    // Retrieves a product by its ID, throws an exception if not found
    private Product getProductById(int id) {
        return products.stream().filter(product -> product.getId().equals(id))
                .findFirst().orElseThrow(() -> new ResourceNotFoundException("Product with id " + id + " not found"));
    }

    // Retrieves all products, checks if the user is authorized to "read" products
    public List<Product> getAllProducts(User user) {
        authorize(user, "read", productResourceBuilder.build());  // User must have "read" permission
        return new ArrayList<>(products);  // Return a copy of the products list
    }

    // Retrieves a product by its ID, checks if the user is authorized to "read" the product
    public Product getProduct(User user, int id) {
        authorize(user, "read", productResourceBuilder.build());
        return getProductById(id);
    }

    // Adds a new product, authorizes the user and creates resource instances and role assignments in Permit
    public Product addProduct(User user, String content) {
        authorize(user, "create", productResourceBuilder.build());  // Check if user can create a product
        Product product = new Product(productIdCounter.incrementAndGet(), user.getKey(), content);  // Create new product

        try {
            // Create resource instance in Permit and assign "vendor" role to the user for this product
            permit.api.resourceInstances.create(new ResourceInstanceCreate(product.getId().toString(), "product").withTenant("default"));
            permit.api.roleAssignments.assign(new RoleAssignmentCreate("vendor", user.getKey()).withResourceInstance("product:" + product.getId()).withTenant("default"));
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException("Failed to create resource instance or role assignment: " + e.getMessage());
        }

        products.add(product);  // Add product to in-memory list
        return product;
    }

    // Updates a product's content, checks if the user is authorized to "update" the product
    public Product updateProduct(User user, int id, String content) {
        Product product = getProductById(id);  // Get the product by its ID
        authorize(user, "update", product);  // Check if user can update the product
        product.setContent(content);  // Update product content
        return product;
    }

    // Deletes a product, checks if the user is authorized to "delete" the product
    public void deleteProduct(User user, int id) {
        boolean isDeleted = products.removeIf(product -> {
            if (product.getId().equals(id)) {
                authorize(user, "delete", product);  // Check if user can delete the product
                return true;
            } else {
                return false;
            }
        });

        if (!isDeleted) {
            throw new ResourceNotFoundException("Product with id " + id + " not found");
        }

        try {
            permit.api.resourceInstances.delete("product:" + id);  // Remove product resource instance from Permit
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }
    }

    // Adds a review to a product, creates a resource instance and relationship in Permit
    public Review addReview(User user, int productId, String content) {
        authorize(user, "create", reviewResourceBuilder.build());  // Check if user can create a review
        Product product = getProductById(productId);  // Get the product by its ID
        Review review = new Review(reviewIdCounter.incrementAndGet(), user.getKey(), content);  // Create new review

        try {
            // Create a resource instance for the review and set relationship with the product
            permit.api.resourceInstances.create(new ResourceInstanceCreate(review.getId().toString(), "review").withTenant("default"));
            permit.api.relationshipTuples.create(new RelationshipTupleCreate("product:" + productId, "parent", "review:" + review.getId()));
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }

        product.addReview(review);  // Add the review to the product
        return review;
    }

    // Updates a review's content, checks if the user is authorized to "update" the review
    public Review updateReview(User user, int productId, int reviewId, String content) {
        Product product = getProductById(productId);  // Get the product by its ID
        Review review = product.getReviews().stream().filter(c -> c.getId().equals(reviewId))
                .findFirst().orElseThrow(() -> new ResourceNotFoundException("Review with id " + reviewId + " not found"));

        authorize(user, "update", review);  // Check if user can update the review
        review.setContent(content);  // Update review content
        return review;
    }

    // Deletes a review, checks if the user is authorized to "delete" the review
    public void deleteReview(User user, int productId, int reviewId) {
        Product product = getProductById(productId);  // Get the product by its ID
        boolean isDeleted = product.getReviews().removeIf(review -> {
            if (review.getId().equals(reviewId)) {
                authorize(user, "delete", review);  // Check if user can delete the review
                return true;
            } else {
                return false;
            }
        });

        if (!isDeleted) {
            throw new ResourceNotFoundException("Review with id " + reviewId + " not found");
        }

        try {
            permit.api.resourceInstances.delete("review:" + reviewId);  // Remove review resource instance from Permit
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }
    }
}

Then in the code below, the ProductController class handles HTTP requests related to products and their reviews. It exposes endpoints for managing products (like creating, updating, deleting, and retrieving) and for managing product reviews.

package com.boostmytool.store.controllers;

import com.boostmytool.store.model.Product;
import com.boostmytool.store.model.Review;
import com.boostmytool.store.service.ProductService;
import io.permit.sdk.enforcement.User;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController  // Indicates that this class is a Spring REST controller
@RequestMapping("/api/products")  // Base URL for all endpoints in this controller
public class ProductController {

    private final ProductService productService;  // ProductService instance to handle product-related operations

    @Autowired  // Autowires ProductService bean automatically
    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    // GET request to retrieve all products
    @GetMapping
    public List<Product> getAllProducts(HttpServletRequest request) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.getAllProducts(currentUser);  // Calls ProductService to get all products for the user
    }

    // GET request to retrieve a product by its ID
    @GetMapping("/{id}")
    public Product getProductById(HttpServletRequest request, @PathVariable("id") int id) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.getProduct(currentUser, id);  // Calls ProductService to get the product by ID for the user
    }

    // POST request to add a new product
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)  // Sets the response status to 201 (Created)
    public Product addProduct(HttpServletRequest request, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.addProduct(currentUser, content);  // Calls ProductService to add a new product
    }

    // PUT request to update an existing product by its ID
    @PutMapping("/{id}")
    public Product updateProduct(HttpServletRequest request, @PathVariable("id") int id, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.updateProduct(currentUser, id, content);  // Calls ProductService to update the product by ID
    }

    // DELETE request to delete a product by its ID
    @DeleteMapping("/{id}")
    public String deleteProduct(HttpServletRequest request, @PathVariable("id") int id) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        productService.deleteProduct(currentUser, id);  // Calls ProductService to delete the product by ID
        return "Deleted product with id " + id;  // Returns a success message after deletion
    }

    // POST request to add a new review to a product by product ID
    @PostMapping("/{id}/review")
    public Review addReview(HttpServletRequest request, @PathVariable("id") int id, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.addReview(currentUser, id, content);  // Calls ProductService to add a review to the product
    }

    // PUT request to update an existing review by product and review ID
    @PutMapping("/{id}/review/{reviewId}")
    public Review updateReview(HttpServletRequest request, @PathVariable("id") int id, @PathVariable("reviewId") int reviewId, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.updateReview(currentUser, id, reviewId, content);  // Calls ProductService to update the review
    }

    // DELETE request to delete a review by product and review ID
    @DeleteMapping("/{id}/review/{reviewId}")
    public String deleteReview(HttpServletRequest request, @PathVariable("id") int id, @PathVariable("reviewId") int reviewId) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        productService.deleteReview(currentUser, id, reviewId);  // Calls ProductService to delete the review
        return "Deleted review with id " + reviewId + " from product " + id;  // Returns a success message after deletion
    }
}

Step 2: Get your Environment API Key

In the UI Dashboard, copy the Environment API Key of the active environment.

Then add the env API key and PDP URL in the application.yaml file.

permit:
  pdpUrl: 'http://localhost:7766'
  apiKey: "Your Permit environment API Key"

Step 3: Deploy Policy Decision Point (PDP)

The Policy Decision Point (PDP) is deployed in your VPC and is in charge of evaluating your authorization requests. The PDP will ensure zero latency, great performance, high availability, and improved security.

Use the command below to pull the Permit.io PDP container from Docker Hub.

docker pull permitio/pdp-v2:latest

Then run the container.

docker run -it -p 7766:7000 --env PDP_DEBUG=True --env PDP_API_KEY=<YOUR_API_KEY> permitio/pdp-v2:latest

Step 4: Running the App

You can run the application using the following Gradle command:

./gradlew bootRun

Viewing and Creating Products

Let’s now interact with the application endpoints using REQBIN.

First, create a new user using the /api/users/signup endpoint.

curl -X POST "http://localhost:8080/api/users/signup" -H "Content-Type: application/json" -d 'johndoe'

You should be able to view the user in your Permit project, under Directory > All Tenants.

Initially, the user has no roles, so it cannot do much. For example, trying to list the products will result in a 403 Forbidden response, as shown below. The 403 error code means the user doesn’t have permissions to access the requested resource, which is products in this case. You can learn more about the difference between 401 and 403 error codes here.

For the user to view a list of products, assign them a viewer role using the command below:

curl -X POST "http://localhost:8080/api/users/assign-role" \
-H "Authorization: Bearer johndoe" \
-H "Content-Type: application/json" \
-d 'viewer'

You should see that user johndoe was assigned role viewer, as shown below:

Since a viewer can create a product, use the command below to create a product with user johndoe.

curl -X POST "http://localhost:8080/api/products" -H "Authorization: Bearer johndoe" -H "Content-Type: application/json" -d 'MacBook'

You should see that a new product is created with ID 1 and that the user johndoe has been added as the vendor.

Adding Reviews To Products

To add reviews to products, create another user called jane.

curl -X POST "http://localhost:8080/api/users/signup" -H "Content-Type: application/json" -d 'jane'

For the user to add a review to products, assign them a viewer role using the command below:

curl -X POST "http://localhost:8080/api/users/assign-role" \
-H "Authorization: Bearer jane" \
-H "Content-Type: application/json" \
-d 'viewer'

Then you can add a review to the product added by johndoe using the command below:

curl -X POST "http://localhost:8080/api/products/1/review" -H "Authorization: Bearer jane" -H "Content-Type: application/json" -d 'The product was in good quality'

Congratulations! You’ve completed the project for this tutorial.

Next Steps

Now that you've learned how to implement fine-grained authorization in your Java and Spring Boot applications using Permit.io, you might want to explore further.

Here are some valuable resources:

• Permit.io docs

• RBAC VS ABAC: Choosing the Right Authorization Policy Model

Before We End

I hope you found this tutorial insightful.

Here are some of my other recent blog posts that you might enjoy:

• Learn React – A Guide to the Key Concepts

• Neon Postgres vs Supabase

• Full Stack Development with Next.js, Clerk, and Neon Postgres

For more tutorials on amazing developer tools, be sure to check out my blog DTA.

Follow me on Twitter to get live updates on my other projects.

Happy coding.

By implementing this advanced approach, you'll have a robust and highly secure authentication mechanism that significantly enhances data protection and user authentication.

Table Of Contents

• What Are JSON Web Tokens (JWTs)?
• Getting Started
• Sending Our Requests
• Testing Database Connection
• Registering Users
• Setting up the JWT Class
• The Encode Method
• The Login Endpoint
• Protected Resources And Decoding JSON Web Tokens
• What Happens Now?
• How to Set Up The Decode Method In Our JWT Class
• Protected Resources
• Checking The Headers For The Correct Authorization Scheme
• Creating Instances In The API Entry Point
• Suggestions
• How to Implement Token Expiration
• Updated Folder Structure
• Conclusion

What Are JSON Web Tokens (JWTs)?

A JSON Web Token is a string composed of three parts, each joined by a period (.), and then base64url encoded.

Here are the three parts of a JWT:

Header: A header consists of metadata about the token, such as the token type and the algorithm used.

 $header = json_encode([
            "alg" => "HS256",
            "typ" => "JWT"
        ]);

        $header = $this->base64urlEncode($header);

Payload: Within the JWT structure, the payload encapsulates specific indices referred to as claims, housing user data that is encoded using base64url.

$payload = [
    "id" => $user['id'],
    "name" => $user["name"]
];

  $payload = $this->base64urlEncode($payload);

Signature: This is generated by creating a hash of the header and payload, combined with a secret key typically generated as either 256 bits or 32 bytes. By convention, the secret key matches the size of the hash output.

We will use the link below to generate a secret key we need for this project:

 $signature = hash_hmac("sha256", $header . "." . $payload, $secret_key, true);
 $signature = $this->base64urlEncode($signature);

A JSON Web Token is simply a combination of the header, payload, and signature, where each component is concatenated together with periods (“.”) in between:

$header . "." . $payload . "." . $signature;

Getting Started

To kickstart this project, please download the project starter from the following link: PHP Authentication with JWT Tutorial.

Once downloaded, carefully review the README.md file included in the repository for comprehensive information regarding pre-installed packages. The file contains essential details such as notes on security and best practices. Taking the time to thoroughly read through the README will ensure a smooth setup and understanding of the project.

To initiate the setup of the project, utilize Git by executing the following command:

git clone https://github.com/Oghenekparobo/php_auth_jwt_tut.git

This command will clone the project repository to your local system, allowing you to proceed with the installation and configuration process.

After cloning the project from GitHub, your project structure should align with the following layout:

project structure on VS Code

project_root/ │ ├── api/ │ ├── .htaccess │ ├── index.php │ └── (other PHP files) │ ├── vendor/ │ ├── (Composer dependencies) │ └── ... │ ├── .env ├── README.md └── (other project files)

In this structure:

• The api/ directory contains PHP files responsible for handling API requests and responses. It includes an .htaccess file for URL rewriting and an index.php file, along with other PHP files for specific functionalities.
• The vendor/ directory contains Composer dependencies installed for the project. These dependencies are managed by Composer and should not be modified directly.
• The .env file contains environment variables necessary for configuring the application environment, such as database credentials and API keys.
• The README.md file provides essential information about the project, including setup instructions, usage guidelines, and any other relevant details.

Ensure that you maintain this structure and follow any instructions provided in the README file to set up and run the project successfully.

Sending Our Requests

When referring to our project, the URL would typically be structured as follows: http://localhost/php_auth_jwt_tut/api. However, depending on the project's name, this URL might vary accordingly. Nonetheless, the base URL remains consistent: [http://localhost/php_auth_jwt_tut/api](http://localhost/php_auth_jwt_tut/api.).

Thanks to our implementation of URL rewriting in the .htaccess file, additional prefixes such as index.php or .php are unnecessary when accessing our URLs. We've meticulously configured our server settings to ensure seamless navigation without these prefixes.

In simpler terms, accessing our project’s API endpoints can be done directly from the base URL: http://localhost/php_auth_jwt_tut/api. This streamlined approach enhances user experience and eliminates unnecessary complexity for this project.

To make testing our project’s API endpoints easier, we can use the index.php file located in the api folder. This file acts as the starting point for our application and contains all the necessary setups.

Firstly, we’ll simply print out any desired output within the index.php file. This helps us confirm that our endpoint is working correctly. Then, we'll test the endpoint by accessing the URL: [http://localhost/php_auth_jwt_tut/api](http://localhost/php_auth_jwt_tut/api.).

Additionally, we’ll set up our database connection to ensure smooth communication between our API endpoints and the database. All the required configurations are included within the bootstrap.php file for convenience. By importing this file into our index.php, managing configurations and imports becomes simpler.

Furthermore, it’s important to note that we’ll be enforcing strict typing throughout our codebase. This means that we’ll specify the types of data our variables and functions can hold or return. This helps maintain consistency and reduces the chances of errors in our code.

Testing Database Connection

Before proceeding with the steps outlined in this section, it is imperative to thoroughly review the README file of this project. This will provide you with comprehensive instructions on how to set up your database properly. In the root of the project, you will find a file named college.sql, which contains the necessary tables for your database. Simply follow the instructions provided in the README file to import and configure the database accordingly.

In the src folder of our project, we find essential classes and gateways, including the necessary database connections for our project. The file responsible for this is database.php, already configured to establish a PDO database connection.

Note: Before use, ensure to adjust or configure the variables in the .env environment file to match your database credentials.

.env file:

DB_HOST= 'db_host'
DB_NAME = 'db_name'
DB_USER = 'db_user'
DB_PASS = 'db_password'
SECRET_KEY = "secret_key"

bootstrap.php:

require dirname(__DIR__)  . '/vendor/autoload.php';

set_error_handler('ErrorHandler::handleError');
set_exception_handler('ErrorHandler::handleException');

$dotenv = Dotenv\Dotenv::createImmutable(dirname(__DIR__));
$dotenv->load();

header("Content-type: application/json; charset=UTF-8");


$database = new Database(
    $_ENV["DB_HOST"],
    $_ENV["DB_NAME"],
    $_ENV["DB_USER"],
    $_ENV["DB_PASS"]
);

The code prepares our application by doing a few key things. First, it loads the necessary files to handle errors and exceptions smoothly. Then, it grabs environment variables from a special file (.env) where we store important settings like database information. After that, it tells the application to send back data in a specific format (JSON). Finally, it sets up a connection to the database using the information from the .env file. This setup ensures our application runs smoothly and securely.

database.php:

class Database
{
    private ?PDO $conn = null;

    public function __construct(
        private string $host,
        private string $name,
        private string $user,
        private string $password
    ) {
    }

    public function getConnection(): ?PDO
    {
        try {
            if ($this->conn === null) {
                $this->conn = new PDO("mysql:host=$this->host;dbname={$this->name}", $this->user, $this->password);
                $this->conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
                $this->conn->setAttribute(PDO::ATTR_EMULATE_PREPARES, false);
                $this->conn->setAttribute(PDO::ATTR_STRINGIFY_FETCHES, false);
            }

            return $this->conn;
        } catch (PDOException $e) {
            echo "Connection failed: " . $e->getMessage();
            return null;
        }
    }
}

Include an echo statement to indicate a successful database connection before returning the $this->conn object. This helps to verify the connection status and ensure smooth operation of the application. For instance:

try {
    if ($this->conn === null) {
        $this->conn = new PDO("mysql:host=$this->host;dbname={$this->name}", $this->user, $this->password);
        $this->conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
        $this->conn->setAttribute(PDO::ATTR_EMULATE_PREPARES, false);
        $this->conn->setAttribute(PDO::ATTR_STRINGIFY_FETCHES, false);

        // Echo message indicating successful database connection
        echo "Database connected successfully.";
    }

    return $this->conn;
} catch (PDOException $e) {
    echo "Connection failed: " . $e->getMessage();
    return null;
}

Proceed to the index.php file to invoke the getConnection function and verify the application's functionality. It's important to note that we've initialized our Database class in our bootstrap PHP file, ensuring seamless integration and operation.

Invoking the getConnection function in the index.php file should look like this:

index.php file

Upon successfully implementing the database connection and firing our request, you can expect the following response:

database connected successfully

Note: Make sure you clear the echo after we are done.

Registering Users

To efficiently manage user data, we will implement a minimal frontend solution by creating a new file named register.php in the root directory of our project. Additionally, we will introduce a stylesheet named style.css to enhance the visual presentation of the registration page.

We will establish a connection to our database, facilitating the seamless addition of users to the user table within our college database. Upon successful user registration, a confirmation message will be echoed to affirm the addition of the user to the database.

register.php:

require __DIR__ . "/vendor/autoload.php";

if ($_SERVER["REQUEST_METHOD"] === "POST") {

    $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
    $dotenv->load();

    $database = new Database(
        $_ENV["DB_HOST"],
        $_ENV["DB_NAME"],
        $_ENV["DB_USER"],
        $_ENV["DB_PASS"]
    );

    $conn = $database->getConnection();

    $sql = "INSERT INTO user (name, username, password_hash)
            VALUES (:name, :username, :password_hash)";

    $stmt = $conn->prepare($sql);

    $password_hash = password_hash($_POST["password"], PASSWORD_DEFAULT);


    $stmt->bindValue(":name", $_POST["name"], PDO::PARAM_STR);
    $stmt->bindValue(":username", $_POST["username"], PDO::PARAM_STR);
    $stmt->bindValue(":password_hash", $password_hash, PDO::PARAM_STR);


    $stmt->execute();

    echo "Thank you for registering.";
    exit;
}

?>
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>User Registration</title>
    <link rel="stylesheet" href="style.css">
</head>

<body>
    <div class="container">
        <h2>User Registration</h2>
        <form action="register.php" method="post">
            <div class="form-group">
                <label for="name">Name:</label>
                <input type="text" id="name" name="name" required>
            </div>
            <div class="form-group">
                <label for="username">Username:</label>
                <input type="text" id="username" name="username" required>
            </div>
            <div class="form-group">
                <label for="password">Password:</label>
                <input type="password" id="password" name="password" required>
            </div>
            <div class="form-group">
                <input type="submit" value="Register">
            </div>
        </form>
    </div>
</body>

</html>

style.css:

body,
html {
  margin: 0;
  padding: 0;
  font-family: Arial, sans-serif;
}

.container {
  background-color: #fff;
  padding: 20px;
  border-radius: 8px;
  box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
  width: 300px;
  margin: 0 auto;
}

h2 {
  text-align: center;
  margin-bottom: 20px;
}

.form-group {
  margin-bottom: 20px;
}

label {
  font-weight: bold;
}

input[type="text"],
input[type="password"] {
  width: 100%;
  padding: 8px;
  border: 1px solid #ccc;
  border-radius: 4px;
  box-sizing: border-box;
}

input[type="submit"] {
  width: 100%;
  padding: 10px;
  border: none;
  background-color: #007bff;
  color: #fff;
  border-radius: 4px;
  cursor: pointer;
}

input[type="submit"]:hover {
  background-color: #0056b3;
}

Note: Ensure that these files are placed in the root directory of your project. The user interface will appear as follows:

Registration process:

user registration form

Successful registration:

successful registration page

Our database structure is illustrated in the image below:

database structure on phpMyAdmin

Kudos! You deserve a big glass of juice for getting to this point, now let’s get to the next part, which is creating an JWT from scratch!

Setting up the JWT Class

In our project template, the Jwt.php file has already been created. Now, let’s proceed to create our Jwt class and implement the logic for encoding and generating a JWT token.

Encoding To JWT

In order to create a JWT, we need to convert our header, payload, and signature to base64url encoding. However, PHP doesn’t support the Base64URL standard, Therefore, we will develop our custom Base64URL encoding method to perform the necessary encoding operation.

Please copy the following code snippet and paste it into the Jwt class located in the src folder.

class Jwt
{

    public function __construct(private string $key)
    {

    }


    private function base64URLEncode(string $text): string
    {

        return str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($text));
    }


}

This class is responsible for encoding JWT tokens using the base64url encoding scheme. It includes a constructor that accepts a key parameter, which presumably represents the secret key used for encoding the tokens. Additionally, it contains a private method named base64URLEncode, which performs the base64URL encoding operation.

The base64URLEncode Method: The base64urlEncode method is a private function within the Jwt class. It takes a string parameter, text, and returns the base64URL encoded version of the input string. The method first applies the standard base64 encoding to the input text using the base64_encode function.

Then, it replaces the characters ‘+’ (plus), ‘/’ (slash), and ‘=’ (equals sign) with ‘-’ (hyphen), ‘_’ (underscore), and an empty string, respectively. This substitution is necessary to ensure compatibility with the base64URL encoding scheme, which uses URL-safe characters. Finally, the method returns the base64URL encoded string.

Overall, the base64URLEncode method provides a crucial functionality for encoding data in JWT tokens using the base64URL encoding scheme, which is commonly used in JWT implementations.

The encode Method

Paste the following code snippet in your Jwt class:

public function encode(array $payload): string
    {

        $header = json_encode([
            "alg" => "HS256",
            "typ" => "JWT"
        ]);

        $header = $this->base64URLEncode($header);
        $payload = json_encode($payload);
        $payload = $this->base64URLEncode($payload);

        $signature = hash_hmac("sha256", $header . "." . $payload, $this->key, true);
        $signature = $this->base64URLEncode($signature);
        return $header . "." . $payload . "." . $signature;
    }

First, we have a class called Jwt. This class helps us create JWT tokens, In the constructor of the Jwt class, we specified a secret key. This secret key is important for creating and verifying the tokens on the signature component.

The encode method is where the magic happens. It takes some data (which we call the payload) and turns it into a JWT token. Here’s how it works:

1. We create a header for the token. This header contains information about how the token is encrypted and what type of token it is. We then turn this header into a base64URL format.
2. Next, we take the payload data (the information we want to include in the token) and turn that into a base64URL format too.
3. After that, we combine the encoded header and payload with our secret key to create a signature. This signature helps ensure that the token hasn’t been tampered with.
4. Finally, we put everything together; the encoded header, payload, and signature to create the final JWT token. This token is what we can use in our applications to authenticate users and authorize access to certain resources.

The base64URLEncode method ensures that data is encoded in a format suitable for URLs, making it safe for transmission over the web. Within our Jwt class, this method is employed internally by the encode function to encode both the header and payload sections of the token.

With that being said, let’s proceed to test and see our first JWT token, hurray!

The Login Endpoint

In our project, the api folder serves as the entry point for requests. Now that we’ve implemented the algorithm to encode and create a JWT token, let’s proceed to test it. To do this, we’ll create a login.php file within our api folder. In this file, we’ll send a request containing the username and password of the user profiled or created in our frontend register.php UI. We’ll pass the required user details in JSON format:

{
    "username": "test",
    "password": "12345"
}

Please integrate the following code snippet into the login.php file located within our api directory:

require __DIR__ . '/bootstrap.php';

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    header('ALLOW: POST');
    exit();
}

$contentType = isset($_SERVER["CONTENT_TYPE"]) ? trim($_SERVER["CONTENT_TYPE"]) : '';


if ($contentType !== 'application/json') {
    http_response_code(415);
    echo json_encode(["message" => "Only JSON content is supported"]);
    exit();
}

$data = json_decode(file_get_contents('php://input'), true);

if ($data === null) {
    http_response_code(400);
    echo json_encode(["message" => "Invalid JSON data"]);
    exit();
}


if (!array_key_exists('username', $data) || !array_key_exists('password', $data)) {
    http_response_code(400);
    echo json_encode(["message" => "Missing login credentials"]);
    exit();
}

This code snippet serves as the backend logic for handling user login requests. It begins by including the bootstrap.php file to initialize essential components. Then, it checks if the incoming request method is POST, returning a “Method Not Allowed” error if not.

Next, it verifies that the content type of the request is JSON, responding with an “Unsupported Media Type” error if not. The code proceeds to decode the JSON data from the request body and checks its validity. If the JSON data is invalid or lacks the “username” and “password” keys, it returns a “Bad Request” error.

Before proceeding with our login endpoint, we need to configure our UserGateway class, which is already available in our project template within the src folder. This class facilitates interaction with the user data in the database. The provided snippet initializes the class and defines a method getByUsername() to fetch user data based on the provided username.

class UserGateway
{

    private PDO $conn;

    public function __construct(Database $database)
    {
        $this->conn = $database->getConnection();
    }


    public function getByUsername(string $username): array | false
    {
        $sql = 'SELECT * FROM user WHERE username = :username';
        $stmt = $this->conn->prepare($sql);
        $stmt->bindValue(':username', $username, PDO::PARAM_STR);

        $stmt->execute();

        return $stmt->fetch(PDO::FETCH_ASSOC);
    }
}

You will see the need for this as we go on.

Proceed to login.php.

Okay after that quick commercial break, we can create a class instance called $user_gateway and pass our $database connection to it. Next, we retrieve user data based on the provided username from the $user_gateway instance using the getByUsername() method. If no user is found (indicating invalid authentication), we return a 401 HTTP response status along with a corresponding error message in JSON format.

We validate the provided password against the hashed password stored in the user data. If the password verification fails, we return a similar 401 status and error message. If authentication is successful, we construct a payload containing the user's ID and name. Subsequently, we create a JWT token by encoding the payload using the Jwt class instantiated with the secret key from the environment variables. Finally, we respond with the generated token in JSON format, allowing access to protected resources, which will be implemented in a later section.

The code to implement this logic would be the following:

$user_gateway = new UserGateway($database);

$user = $user_gateway->getByUsername($data['username']);

if ($user === false) {
    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}

if (!password_verify($data['password'], $user['password_hash'])) {
    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}


$payload = [
    "id" => $user['id'],
    "name" => $user["name"]
];


$JwtController = new Jwt($_ENV["SECRET_KEY"]);

$token =$$JwtController->encode($payload);

echo json_encode(["token" => $token]);

Full login.php code:

<?php

require __DIR__ . '/bootstrap.php';

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    header('ALLOW: POST');
    exit();
}

$contentType = isset($_SERVER["CONTENT_TYPE"]) ? trim($_SERVER["CONTENT_TYPE"]) : '';


if ($contentType !== 'application/json') {
    http_response_code(415);
    echo json_encode(["message" => "Only JSON content is supported"]);
    exit();
}

$data = json_decode(file_get_contents('php://input'), true);

if ($data === null) {
    http_response_code(400);
    echo json_encode(["message" => "Invalid JSON data"]);
    exit();
}


if (!array_key_exists('username', $data) || !array_key_exists('password', $data)) {
    http_response_code(400);
    echo json_encode(["message" => "Missing login credentials"]);
    exit();
}

$user_gateway = new UserGateway($database);

$user = $user_gateway->getByUsername($data['username']);

if ($user === false) {
    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}

if (!password_verify($data['password'], $user['password_hash'])) {
    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}


require __DIR__ . "/tokens.php";

$refresh_token_gateway = new RefreshTokenGateway($database, $_ENV["SECRET_KEY"]);

$refresh_token_gateway->create($refresh_token, $refresh_token_expiry);

Now that we have set up our login endpoint, established database connections, and implemented the JWT encoding algorithm, nothing stands in our way of obtaining our first JWT token. Let us proceed to test our application with the following steps:

1. Please navigate to our user interface for registering users. The URL should be http://localhost/php_auth_jwt_tut/register.php if you followed the project structure.
2. Send the username and password of the created user to the login endpoint (http://localhost/php_auth_jwt_tut/api/login.php) in JSON format, like this, and fire the request:

endpoint testing

Voila! Just like that, we obtain our JWT token!

Protected Resources And Decoding JSON Web Tokens

Having successfully generated a JWT token, let us now explore how we can safeguard our resources and verify the token’s contents by decoding it.

You’ll find that our controller classes, StudentController.php, and the gateway class StudentGateway.php, situated in the src folder, has already been configured with essential methods. Now, all that's left is to instantiate these classes in our index.php, serving as the entry point for our requests in the api folder.

To do this add the following code snippet in the index.php file located at the api folder of our project:

<?php

require __DIR__ . '/bootstrap.php';

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    header('ALLOW: POST');
    exit();
}

$contentType = isset($_SERVER["CONTENT_TYPE"]) ? trim($_SERVER["CONTENT_TYPE"]) : '';


if ($contentType !== 'application/json') {
    http_response_code(415);
    echo json_encode(["message" => "Only JSON content is supported"]);
    exit();
}

$data = json_decode(file_get_contents('php://input'), true);

if ($data === null) {
    http_response_code(400);
    echo json_encode(["message" => "Invalid JSON data"]);
    exit();
}


if (!array_key_exists('username', $data) || !array_key_exists('password', $data)) {
    http_response_code(400);
    echo json_encode(["message" => "Missing login credentials"]);
    exit();
}

$user_gateway = new UserGateway($database);

$user = $user_gateway->getByUsername($data['username']);

if ($user === false) {
    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}

if (!password_verify($data['password'], $user['password_hash'])) {
    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}


$payload = [
    "id" => $user['id'],
    "name" => $user["name"]
];


$JwtController = new Jwt($_ENV["SECRET_KEY"]);

$token =$JwtController->encode($payload);

echo json_encode(["token" => $token]);

$user = new UserGateway($database);


$gateway = new StudentGateway($database);

$controller = new StudentController($gateway);


$controller->processRequest($_SERVER['REQUEST_METHOD']);

How the files are structured at this current stage:

file structure on VS Code

Please note that upon testing the endpoint (http://localhost/phpAuthJWT/api) at this point, you’ll receive the following result, without any restrictions applied:

endpoint testing

Note: After setting up the database connection and importing the provided file, college.sql, as instructed, the tables, including the “students” table, are populated with pre-added data. This enables us to view the student details that are currently visible.

What Happens Now?

We establish a custom URL endpoint to retrieve data via the GET HTTP method. The URL, [http://localhost/phpAuthJWT/api/](http://localhost/phpAuthJWT/api/getALLStudents)getAllStudents, will remain functional due to the server configuration specified in our .htaccess file located within the api folder. When making requests to this URL, we’ll include our token in the header using the standard HTTP Authorization request header, adhering to the bearer token format:

Authorization: Bearer

In our src folder, we have set up an Auth class where we will create a method to validate the JWT token. This method verifies if the token is provided in the HTTP header and decodes it.

How to Set Up The Decode Method In Our JWT Class

When setting up the decoding functionality in the Jwt class, as we did with the encoding method, we will ensure that our Jwt class, located in the src folder of our project within the jwt.php file handles this task. To achieve this, we will incorporate the following code snippets into our Jwt class – the new methods are the decode and base64UrlDecode methods, thus completing its structure. The final code will resemble the following:

class Jwt
{

    public function __construct(private string $key)
    {

    }

    public function encode(array $payload): string
    {

        $header = json_encode([
            "alg" => "HS256",
            "typ" => "JWT"
        ]);

        $header = $this->base64URLEncode($header);
        $payload = json_encode($payload);
        $payload = $this->base64URLEncode($payload);

        $signature = hash_hmac("sha256", $header . "." . $payload, $this->key, true);
        $signature = $this->base64URLEncode($signature);
        return $header . "." . $payload . "." . $signature;
    }



    public function decode(string $token): array
    {
        if (
            preg_match(
                "/^(?<header>.+)\.(?<payload>.+)\.(?<signature>.+)$/",
                $token,
                $matches
            ) !== 1
        ) {

            throw new InvalidArgumentException("invalid token format");
        }

        $signature = hash_hmac(
            "sha256",
            $matches["header"] . "." . $matches["payload"],
            $this->key,
            true
        );

        $signature_from_token = $this->base64URLDecode($matches["signature"]);

        if (!hash_equals($signature, $signature_from_token)) {

            // throw new Exception("signature doesn't match");
            throw new InvalidSignatureException;
        }

        $payload = json_decode($this->base64URLDecode($matches["payload"]), true);

        return $payload;
    }


    private function base64URLEncode(string $text): string
    {

        return str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($text));
    }

    private function base64URLDecode(string $text): string
    {
        return base64_decode(
            str_replace(
                ["-", "_"],
                ["+", "/"],
                $text
            )
        );
    }


}

Decode Method:

The decode method is responsible for decoding a JWT token into its respective header and payload components. Here's a brief overview of what it does:

1. Token Validation: First, it verifies if the provided token follows the expected format of three sections separated by periods.
2. Signature Verification: It recalculates the signature based on the header and payload from the token and compares it with the signature provided in the token. This step ensures the integrity of the token.
3. Payload Extraction: If the signature verification passes, it decodes the payload component of the token from base64 URL encoding into a JSON format. This decoded payload contains information about the user associated with the token.
4. Finally, it returns the decoded payload as an associative array.

base64URLDecode Method:

The base64URLDecode method is a helper function used specifically for decoding strings that have been encoded using base64 URL encoding. Here's a breakdown of its functionality:

1. Replace Characters: It first replaces the characters - and _ in the encoded string with + and / respectively. This step is necessary because URL encoding replaces certain characters for safe transmission over the web.
2. Base64 Decoding: After character replacement, it performs the standard base64 decoding operation on the modified string.
3. Finally, it returns the decoded string.

In summary, the decode method validates and extracts the payload from a JWT token, while the base64URLDecode method assists in decoding strings encoded using base64 URL encoding, ensuring the integrity and accuracy of the decoded data.

Protected Resources

Now that we have completed the setup, let’s finalize our Jwt class. It’s essential to restrict access to our endpoints without the required authorization header. For instance, accessing the URL [http://localhost/phpAuthJWT/api/](http://localhost/phpAuthJWT/api/getALLStudents)getAllStudents should be restricted if the necessary authorization header is absent, and access to resources should be denied if the URL is incorrect.

To achieve this, add the following code snippet to the top of your index.php file, which serves as the entry point for accessing our student data. Paste this code after importing the bootstrap.php configuration file.

require __DIR__ . '/bootstrap.php';

$path = parse_url($_SERVER["REQUEST_URI"], PHP_URL_PATH);

$parts = explode("/", $path);


$resource = $parts[3];

$id = $parts[4] ?? null;

if ($resource != "getAllStudents") {

    http_response_code(404);
    exit;
}

This snippet shows how we extracted the path from the requested URI using the parse_url() function, isolating the endpoint accessed by the user. Then splitting the path into segments using the explode() function, allowing us to identify the requested resource. If the requested resource is not “getAllStudents”, indicating an invalid endpoint, the code responds with a 404 Not Found status code, signaling that the requested resource does not exist. This ensures that only valid endpoints can be accessed, preventing unauthorized access to our API’s resources.

Note: To verify that our project is functioning as intended, send a request to the “getAllStudents” endpoint at http://localhost/phpAuthJWT/api/getAllStudents

This request will help us ensure that our API is correctly configured and capable of retrieving all student data.

Checking The Headers For The Correct Authorization Scheme

We have established a custom URL, but it is crucial to verify that the JWT token provided in the header is valid. To accomplish this, we will utilize the Auth class, which is already available in our project’s src folder. This class, which was provided with our project template, will assist in ensuring the integrity of the JWT token.

Auth.php:

class Auth
{



    public function __construct(private UserGateway $user_gateway, private Jwt $JwtCtrl)
    {
    }



    public function authenticateJWTToken(): bool
    {

        if (!preg_match("/^Bearer\s+(.*)$/", $_SERVER["HTTP_AUTHORIZATION"], $matches)) {
            http_response_code(400);
            echo json_encode(["message" => "incomplete authorization header"]);
            return false;
        }

        try {
            $data = $this->JwtCtrl->decode($matches[1]);
        } catch (InvalidSignatureException) {

            http_response_code(401);
            echo json_encode(["message" => "invalid signature"]);
            return false;
        } catch (Exception $e) {

            http_response_code(400);
            echo json_encode(["message" => $e->getMessage()]);
            return false;
        }



        return true;
    }
}

This class is responsible for handling the authentication of JWT tokens. Within the class, we have a constructor method that initializes the Auth object with instances of two other classes: UserGateway and Jwt.

Absolutely! Let’s break down the code snippet in a more detailed and narrative manner:

In the provided PHP code snippet, we defined a class named Auth. This class is responsible for handling the authentication of JWT tokens. Within the class, we have a constructor method that initializes the Auth object with instances of two other classes: UserGateway and Jwt.

class Auth
{
    public function __construct(private UserGateway $user_gateway, private Jwt $JwtCtrl)
    {
    }
    // Other methods will go here...
}

The constructor method allows the Auth class to interact with user data through the UserGateway class and handle JWT tokens using the Jwt class.

Next, we have a method called authenticateJWTToken(), which is tasked with verifying the validity of a JWT token present in the HTTP authorization header of incoming requests.

public function authenticateJWTToken(): bool
{

}

Within the authenticateJWTToken() method, the code first checks if the authorization header is properly formatted and contains a valid JWT token.

if (!preg_match("/^Bearer\s+(.*)$/", $_SERVER["HTTP_AUTHORIZATION"], $matches)) {
    http_response_code(400);
    echo json_encode(["message" => "incomplete authorization header"]);
    return false;
}

If the authorization header is incomplete or improperly formatted, the method returns a 400 Bad Request response along with a message indicating the issue.

Next, the code attempts to decode the JWT token using the decode() method of the Jwt class. If the decoding process fails due to an invalid signature or any other exception, appropriate HTTP response codes and error messages are returned.

try {
    $data = $this->JwtCtrl->decode($matches[1]);
} catch (InvalidSignatureException) {
    http_response_code(401);
    echo json_encode(["message" => "invalid signature"]);
    return false;
} catch (Exception $e) {
    http_response_code(400);
    echo json_encode(["message" => $e->getMessage()]);
    return false;
}

If the JWT token is successfully decoded without any exceptions, the method returns true, indicating that the authentication process was successful.

The authenticateJWTToken() method ensures that incoming requests contain a valid JWT token in the Authorization header and handles various error scenarios gracefully to provide appropriate feedback to clients interacting with the API.

Creating Instances In The API Entry Point

Now that we have finished setting up our methods let us add our class instances to enable the protection of our resources from unauthorized users.

index.php:

declare(strict_types=1);

require __DIR__ . '/bootstrap.php';

$path = parse_url($_SERVER["REQUEST_URI"], PHP_URL_PATH);

$parts = explode("/", $path);


$resource = $parts[3];

if ($resource != "getAllStudents") {

    http_response_code(404);
    exit;
}


$user = new UserGateway($database);


$JwtCtrl = new Jwt($_ENV["SECRET_KEY"]);

$auth = new Auth($user, $JwtCtrl);

if (!$auth->authenticateJWTToken()) {
    exit;
}



$gateway = new StudentGateway($database);

$controller = new StudentController($gateway);



$controller->processRequest($_SERVER['REQUEST_METHOD']);

Once we’ve incorporated the provided snippet into our index.php, it's crucial to observe the different scenarios that occur when we access our API endpoint at http://localhost/phpAuthJWT/api/getAllStudents.

By accessing this URL, we can witness several possible outcomes, each indicative of a different state or functionality within our application. These outcomes may include:

1. Successful Response: If the authentication process is successful and the JWT token is valid, the API should return a response containing the desired data, such as a list of all students.
2. Invalid Token: In case the JWT token provided in the request’s Authorization header is invalid, expired, or improperly formatted, the API should respond with an error message indicating the issue. This ensures that only authorized users can access the protected resources.
3. Unauthorized Access: If the request does not include a JWT token or lacks proper authorization, the API should respond with a 401 Unauthorized status code, indicating that access to the requested resource is restricted.
4. Invalid Endpoint: If the URL provided does not match any of the defined endpoints or routes within our application, the API should respond with a 404 Not Found status code, signaling that the requested resource does not exist.

By examining these outcomes, we can gain insights into the functionality and reliability of our API, ensuring that it behaves as intended and provides appropriate responses to different types of requests and scenarios.

Working properly with Authorization Header: http://localhost/phpAuthJWT/api/getAllStudents

endpoint testing

Not working properly without Authorization Header: http://localhost/phpAuthJWT/api/getAllStudents

endpoint testing

Suggestions

After setting up our JWT, there’s a whole new world to explore. You can experiment with our API by creating custom URLs for specific tasks, such as finding students by name or letting users create and update their own student profiles by tracking the user_id of the user. You can use various HTTP methods like GET, POST, PATCH, and DELETE to manage data effectively. While this article covers the basics, there’s an abundance of possibilities waiting to be explored when comes to creating a robust API.

JWT tokens provide a convenient and efficient way to handle authentication and authorization in web applications. However, it’s crucial to recognize that they are not absolutely foolproof. It’s essential to avoid putting sensitive information in the payload component of the token, as the payload is typically base64URLEncoded and can be easily decoded. Additionally, the secret key used to sign the token should be kept hidden and never exposed to public information, as it can compromise the security of the system.

In JWT tokens, the header, payload, and signature are all base64URLEncoded, ensuring compatibility with URLs and safe transmission over the web. However, it’s important to note that JWT tokens should have an expiration time to mitigate the risk of token misuse. In the next part, we will explore how to implement token expiration and introduce refresh tokens to enhance the security of our authentication system.

We have explored the implementation of JSON Web Tokens (JWTs) and learned how to utilize them. However, a significant security concern persists: our tokens, specifically referred to as access tokens in this context, can currently access our resources indefinitely. This practice does not align with industry standards. To enhance security, we should implement token expiration for our JWTs. Additionally, adopting a two-token system comprising a refresh token alongside our access token is recommended.

How to Implement Token Expiration

We'll focus on implementing access tokens and refresh tokens. Any necessary additions to our project or database structure will be introduced as we progress through the implementation.

Let's get right into it!

Access tokens must have an expiration mechanism. We need our JWT tokens to automatically expire after a short period, requiring users to request a new token once it expires.

Prompting users to log in every minute when the token expires is not user-friendly. Instead, we can issue a refresh token. The refresh token typically has a longer lifespan than the access token. When the access token expires, the client can leverage the refresh token to obtain a new access token. We will incorporate an endpoint for the client to refresh the access token seamlessly.

Continuing from where we left off, we will now create a refresh endpoint in our api folder. As we know this endpoint serves as our entry point for handling requests related to token refreshing and will be named refresh.php.

<?php
declare(strict_types=1);

require __DIR__ . "/bootstrap.php";

if ($_SERVER["REQUEST_METHOD"] !== "POST") {

    http_response_code(405);
    header("Allow: POST");
    exit;
}

$data = (array) json_decode(file_get_contents("php://input"), true);

if ( ! array_key_exists("token", $data)) {

    http_response_code(400);
    echo json_encode(["message" => "missing token"]);
    exit;
}

$JwtController = new Jwt($_ENV["SECRET_KEY"]);

It checks if the incoming request method is POST; otherwise, it responds with a 405 HTTP status code and allows only POST requests. The script then parses JSON data from the request body, ensuring it contains a “token” key. If the token is missing, it responds with a 400 status code and a JSON message indicating the absence of the token. Finally, the script initializes a Jwt object with a secret key from the environment variables for further token processing.

refresh.php file

Before proceeding with the setup of our refresh endpoint, we will create a class called RefreshTokenGateway.php to handle operations related to refreshing tokens. The RefreshTokenGateway class includes methods for creating, deleting, fetching, and managing expired refresh tokens within our database.

The RefreshTokenGateway class utilizes a PDO connection and a secret key for hashing tokens. Its constructor initializes the database connection and secret key variables. The create method generates a hash for the token and inserts it into the refresh_token table along with its expiration time. The delete method removes a token from the database based on its hash value. The getByToken method retrieves token details based on its hash. Lastly, the deleteExpired method deletes expired tokens from the database, ensuring efficient token management.

Overall, the RefreshTokenGateway class provides essential functionality for maintaining and handling refresh tokens securely within our web application.

RefreshTokenGateway.php:

<?php

class RefreshTokenGateway
{
    private PDO $conn;
    private string $key;

    public function __construct(Database $database, string $key)
    {
        $this->conn = $database->getConnection();
        $this->key = $key;
    }

    public function create(string $token, int $expiry): bool
    {
        $hash = hash_hmac("sha256", $token, $this->key);

        $sql = "INSERT INTO refresh_token (token_hash, expires_at)
                VALUES (:token_hash, :expires_at)";

        $stmt = $this->conn->prepare($sql);

        $stmt->bindValue(":token_hash", $hash, PDO::PARAM_STR);
        $stmt->bindValue(":expires_at", $expiry, PDO::PARAM_INT);

        return $stmt->execute();
    }

    public function delete(string $token): int
    {
        $hash = hash_hmac("sha256", $token, $this->key);

        $sql = "DELETE FROM refresh_token
                WHERE token_hash = :token_hash";

        $stmt = $this->conn->prepare($sql);

        $stmt->bindValue(":token_hash", $hash, PDO::PARAM_STR);

        $stmt->execute();

        return $stmt->rowCount();
    }

    public function getByToken(string $token): array | false
    {
        $hash = hash_hmac("sha256", $token, $this->key);

        $sql = "SELECT *
                FROM refresh_token
                WHERE token_hash = :token_hash";

        $stmt = $this->conn->prepare($sql);

        $stmt->bindValue(":token_hash", $hash, PDO::PARAM_STR);

        $stmt->execute();

        return $stmt->fetch(PDO::FETCH_ASSOC);
    }

    public function deleteExpired(): int
    {
        $sql = "DELETE FROM refresh_token
                WHERE expires_at < UNIX_TIMESTAMP()";

        $stmt = $this->conn->query($sql);

        return $stmt->rowCount();
    }
}

Updated Folder Structure

From the code snippet provided for our [RefreshTokenGateway](https://github.com/Oghenekparobo/php_auth_jwt_tut/blob/refresh-token/src/RefreshTokenGateway.php) class, it's evident that a new table has been incorporated into our database. We have updated our college.sql file to accommodate this change. Kindly import the updated SQL file into your database, following the process outlined in the first part of this article.

Additionally, a new exception class named TokenExpiredException has been introduced. Ensure to update your project structure or files accordingly to include this new exception handling. This ensures that your project remains up-to-date and aligned with the latest changes in token management.

Before we finish setting up our refresh endpoint for obtaining a new access token after expiration, let’s integrate the retrieval of our refresh token and access token into our login endpoint. We have the RefreshTokenGateway class to manage refresh tokens, and we'll create the tokens.php file in our api folder for token creation, which will be used in both the refresh and login endpoints. This approach ensures a straightforward and unified token management process across our application.

tokens.php:

<?php

$payload = [
    "sub" => $user["id"],
    "name" => $user["name"],
    "exp" => time() + 20
];

$JwtController = new Jwt($_ENV["SECRET_KEY"]);

$access_token = $JwtController->encode($payload);

$refresh_token_expiry = time() + 432000;

$refresh_token = $JwtController->encode([
    "sub" => $user["id"],
    "exp" => $refresh_token_expiry
]);

echo json_encode([
    "access_token" => $access_token,
    "refresh_token" => $refresh_token
]);

The main difference between the refresh token and the payload (access token claims) is that the payload contains detailed user information like ID and name, and its expiration is shorter (20 seconds) for security reasons. On the other hand, the refresh token only contains the user ID and has a longer expiration (5 days) to allow for longer-lasting authentication without needing frequent logins. This separation of tokens and their respective lifespans enhances security and user convenience in token-based authentication systems.

login.php:

<?php

require __DIR__ . '/bootstrap.php';

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    header('ALLOW: POST');
    exit();
}

$contentType = isset($_SERVER["CONTENT_TYPE"]) ? trim($_SERVER["CONTENT_TYPE"]) : '';


if ($contentType !== 'application/json') {
    http_response_code(415);
    echo json_encode(["message" => "Only JSON content is supported"]);
    exit();
}

$data = json_decode(file_get_contents('php://input'), true);

if ($data === null) {
    http_response_code(400);
    echo json_encode(["message" => "Invalid JSON data"]);
    exit();
}


if (!array_key_exists('username', $data) || !array_key_exists('password', $data)) {
    http_response_code(400);
    echo json_encode(["message" => "Missing login credentials"]);
    exit();
}

$user_gateway = new UserGateway($database);

$user = $user_gateway->getByUsername($data['username']);

if ($user === false) {
    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}

if (!password_verify($data['password'], $user['password_hash'])) {
    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}


require __DIR__ . "/tokens.php";

$refresh_token_gateway = new RefreshTokenGateway($database, $_ENV["SECRET_KEY"]);

$refresh_token_gateway->create($refresh_token, $refresh_token_expiry);

Testing our login endpoint with the right parameters should result in the following response:

endpoint testing

Note: Before we move on let us update our Jwt class, the decode function to be specific. The updated decode function in the Jwt class checks if a token has the correct format, ensuring it has a header, payload, and signature. It then verifies the token's signature to confirm it hasn't been tampered with. After that, it decodes the payload (containing user information and expiration time) from the token. Lastly, it checks if the token has expired, throwing an error if it has. Overall, these steps ensure the token is valid, unaltered, and within its expiration period for secure usage in the application.

Jwt class:

<?php

class Jwt
{

    public function __construct(private string $key)
    {

    }

    public function encode(array $payload): string
    {

        $header = json_encode([
            "alg" => "HS256",
            "typ" => "JWT"
        ]);

        $header = $this->base64URLEncode($header);
        $payload = json_encode($payload);
        $payload = $this->base64URLEncode($payload);

        $signature = hash_hmac("sha256", $header . "." . $payload, $this->key, true);
        $signature = $this->base64URLEncode($signature);
        return $header . "." . $payload . "." . $signature;
    }



    public function decode(string $token): array
    {
        if (preg_match("/^(?<header>.+)\.(?<payload>.+)\.(?<signature>.+)$/",
                   $token,
                   $matches) !== 1) {

            throw new InvalidArgumentException("invalid token format");
        }

        $signature = hash_hmac("sha256",
                               $matches["header"] . "." . $matches["payload"],
                               $this->key,
                               true);   

        $signature_from_token = $this->base64urlDecode($matches["signature"]);

        if ( ! hash_equals($signature, $signature_from_token)) {

            throw new InvalidSignatureException;
        }

        $payload = json_decode($this->base64urlDecode($matches["payload"]), true);

        if ($payload["exp"] < time()) {

            throw new TokenExpiredException;
        }

        return $payload;
    }


    private function base64URLEncode(string $text): string
    {

        return str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($text));
    }

    private function base64URLDecode(string $text): string
    {
        return base64_decode(
            str_replace(
                ["-", "_"],
                ["+", "/"],
                $text
            )
        );
    }


}

Updated UserGateway.php class

<?php

class UserGateway
{
    private PDO $conn;

    public function __construct(Database $database)
    {
        $this->conn = $database->getConnection();
    }

    public function getByAPIKey(string $key): array | false
    {
        $sql = "SELECT *
                FROM user
                WHERE api_key = :api_key";

        $stmt = $this->conn->prepare($sql);

        $stmt->bindValue(":api_key", $key, PDO::PARAM_STR);

        $stmt->execute();

        return $stmt->fetch(PDO::FETCH_ASSOC);
    }

    public function getByUsername(string $username): array | false
    {
        $sql = "SELECT *
                FROM user
                WHERE username = :username";

        $stmt = $this->conn->prepare($sql);

        $stmt->bindValue(":username", $username, PDO::PARAM_STR);

        $stmt->execute();

        return $stmt->fetch(PDO::FETCH_ASSOC);
    }

    public function getByID(int $id): array | false
    {
        $sql = "SELECT *
                FROM user
                WHERE id = :id";

        $stmt = $this->conn->prepare($sql);

        $stmt->bindValue(":id", $id, PDO::PARAM_INT);

        $stmt->execute();

        return $stmt->fetch(PDO::FETCH_ASSOC);
    }
}

Fnishing up with the ‘refresh’ endpoint:

<?php
declare(strict_types=1);

require __DIR__ . "/bootstrap.php";

if ($_SERVER["REQUEST_METHOD"] !== "POST") {

    http_response_code(405);
    header("Allow: POST");
    exit;
}

$data = (array) json_decode(file_get_contents("php://input"), true);

if ( ! array_key_exists("token", $data)) {

    http_response_code(400);
    echo json_encode(["message" => "missing token"]);
    exit;
}

$JwtController = new Jwt($_ENV["SECRET_KEY"]);

try {
    $payload = $JwtController->decode($data["token"]);

} catch (Exception) {

    http_response_code(400);
    echo json_encode(["message" => "invalid token"]);
    exit;
}

$user_id = $payload["sub"];


$refresh_token_gateway = new RefreshTokenGateway($database, $_ENV["SECRET_KEY"]);

$refresh_token = $refresh_token_gateway->getByToken($data["token"]);

if ($refresh_token === false) {

    http_response_code(400);
    echo json_encode(["message" => "invalid token (not on whitelist)"]);
    exit;
}

$user_gateway = new UserGateway($database);

$user = $user_gateway->getByID($user_id);

if ($user === false) {

    http_response_code(401);
    echo json_encode(["message" => "invalid authentication"]);
    exit;
}

require __DIR__ . "/tokens.php";

$refresh_token_gateway->delete($data["token"]);

$refresh_token_gateway->create($refresh_token, $refresh_token_expiry);

The code then proceeds to validate the HTTP request method, ensuring that only POST requests are accepted for sensitive operations like token handling. This validation is significant as it helps prevent unauthorized access and ensures the security of authentication processes.

Next, the code retrieves and decodes JSON data from the request body, specifically looking for a “token” key. This token is pivotal for authentication and access control within the application. If the token is missing, the code responds with an error message, highlighting the importance of including valid tokens for secure access.

The decoded token is then passed to the JwtController instance to decode its payload and validate its authenticity. This step is crucial as it verifies the integrity of the token and ensures that it hasn't been tampered with or forged.

Furthermore, the code interacts with a RefreshTokenGateway to manage refresh tokens, which play a vital role in generating access tokens securely. Refresh tokens provide a way to obtain new access tokens without requiring the user to log in again, enhancing user experience and maintaining continuous access to resources.

When a user logs in via the login endpoint, two crucial tokens are provided: an access token and a refresh token. The access token grants immediate access to resources, while the refresh token serves as a long-term authorization tool. If the access token expires, the refresh token is then passed to the refresh endpoint. This action triggers the generation of a new access token, which, in turn, creates a fresh refresh token. This process forms a robust and secure mechanism ensuring continuous access to resources while maintaining high levels of security and user convenience.

endpoint testing

endpoint testing

Conclusion

In the analyzed code snippets and explanations regarding token management, authentication mechanisms, and refresh token usage within a web application, several key conclusions can be drawn.

Firstly, token-based authentication, especially using JSON Web Tokens, offer a secure and efficient way to handle user authentication and authorization processes. JWTs encapsulate user information in a compact format and are digitally signed, ensuring their integrity and authenticity.

Secondly, the implementation of access tokens and refresh tokens enhances security and user experience. Access tokens provide immediate access to resources and have a short lifespan, promoting security by limiting their usability in case of unauthorized access. On the other hand, refresh tokens have a longer lifespan and enable users to obtain new access tokens without repeated authentication, thereby improving user convenience.

Furthermore, strict typing enforcement, proper validation of HTTP request methods, and token format checks are crucial elements in ensuring the robustness and reliability of token-based authentication systems. These practices help prevent common vulnerabilities such as unauthorized access attempts, token tampering, and invalid token usage.

Overall, by combining secure token management practices, effective authentication mechanisms, and adherence to coding best practices, web applications can achieve a high level of security, user-friendliness, and resilience against potential threats.

See the full code here.

In today's digital age, managing who can access what resources is more critical than ever. That's where ReBAC comes in. It's a fresh take on authorization, focusing on the relationships between different entities rather than just assigning static roles or attributes.

Traditional access control methods, like Role-Based Access Control (RBAC), assign specific roles to users. While this works in many cases, it can become difficult, especially in dynamic environments where roles and permissions need to adapt quickly. On the other hand, Attribute-Based Access Control (ABAC) offers flexibility based on user attributes, but it can get complex to manage.

Now, ReBAC is all about understanding the intricate web of relationships between entities. Whether it's within an organization, a social media platform, or a project management tool, ReBAC ensures that access control remains dynamic and context-aware.

By the end of this tutorial, you'll have a clear understanding of ReBAC and be able to model a ReBAC scenario.

Key Takeaways

• ReBAC Principles: Understand how ReBAC uses relationships between entities for access control, differing from traditional models.
• Policy Visualization: Learn about representing policies as graphs for clearer management.
• Real-World Examples: Explore ReBAC's application in scenarios like social media platforms and project management tools.
• Benefits of ReBAC: Discover the advantages like granular control and dynamic policy adaptation.
• Permission Models: Get familiar with ReBAC's common models such as Ownership and Hierarchical Models.
• Permify Implementation: Step-by-step guide to implement ReBAC in Permify, including entity definition, relationship establishment, and permissions setup.

What is Relationship-Based Access Control (ReBAC)?

Traditional access control methods, like Role-Based Access Control (RBAC), assign specific roles to users, like giving someone a badge that says "manager" or "employee". But what if the roles aren't so clear-cut, and relationships between people and resources matter more?

That's where Relationship-Based Access Control (ReBAC) steps in. Instead of relying solely on predefined roles or attributes, ReBAC considers the intricate web of connections between users, resources, and other entities. It's like saying, "You can access this because you're connected to it in this specific way", rather than just based on a generic label.

But how does ReBAC actually do this? ReBAC examines the relationships between entities, such as users and resources, and uses these connections to determine access.

Let's break it down further. In our everyday lives, we have relationships that matter. Think about social media – you can see certain posts because you're friends with someone or because someone you follow liked it. ReBAC takes this idea and applies it to access control in systems.

Policy as a Graph

At the core of ReBAC lies the concept of "Policy as a Graph". This idea shows the importance of visualizing access policies through relationships.

Imagine that you have a detailed map of a bustling city. It doesn't just show buildings but also the connections between them – the roads, bridges, and pathways that link everything together.

Now, picture this map as a representation of your organization. Instead of buildings, it represents team members, departments, and their roles. The connections between them symbolize the relationships that dictate access.

This is what we mean by "Policy as a Graph" in ReBAC.

In simpler terms, access policies are like interconnected dots on a graph. Each dot represents an entity, and the lines between them signify the relationships influencing authorization. It's a visual representation that helps us understand the complex web of connections that govern access.

How is ReBAC Different from Other Control Models?

Now, let's explore how ReBAC sets itself apart from other access control models, such as Role-Based Access Control (RBAC).

Unlike traditional models, ReBAC doesn't rely solely on rigid roles or attributes. Instead, it works on deriving permissions from existing relationships. Here's how it stands out:

• Role Derivation:ReBAC allows the creation of authorization policies based on pre-existing relationships. This means that assigning a user a certain role in one context might automatically extend that role to related entities, saving the need for manual assignment.
• Resource Roles:Unlike global roles in traditional models, ReBAC introduces the concept of resource-specific roles (for example: Folder#Owner). These roles are exclusive to the context of a particular resource, ensuring that permissions are relevant and tailored to that specific entity.

Real-World Examples

To better understand how Relationship-Based Access Control (ReBAC) functions in the real world, let's explore two scenarios that mimic everyday complexities.

These examples will help illustrate how ReBAC excels in managing intricate access dynamics.

Instagram-like Social Platform

Consider an Instagram-inspired platform where users hold individual accounts. Each account consists of user-generated content, namely pictures (Pic 1 and Pic 2), chat interactions with different users, and project collaboration.

The user account possesses a list of blocked users who are restricted from viewing pictures. Here's a detailed breakdown of the entities and permissions:

1. Account Entities

• User Account: Represents individual user accounts on the platform.
• Pictures (Pic 1 and Pic 2): Depict user-generated visual content.
• Chats: Captures interaction histories with different users.
• Blocked Users List: Maintains a list of users who are blocked from viewing pictures.

2. Permissions Dynamics

Account Access Permissions:

• "Account#Owner" grants ownership, allowing the user account holder to manage all aspects.
• "Account#Viewer" enables others to view the user's account.

Picture Management Permissions:

• "Picture#Owner" designates ownership at the picture level, allowing the user to edit, delete, and upload pictures.
• "Picture#Viewer" permits normal viewers to only view pictures.
• "BlockedUser#CannotView" ensures that blocked users cannot view pictures.

Chat Interaction Permissions:

• "Chat#Participant" allows users to participate in chat interactions.
• "Chat#BlockedUser" restricts certain users from participating in chats.

Account Editing Permissions:

• "Account#Edit" grants the ability to update account details and preferences.

Instagram-like Social Platform Entities

In this scenario, the "#" symbol represents the relationship between entities when defining permissions. For example, "Account#Owner" signifies ownership of the user account, allowing the account holder to manage all aspects of their account.

Project Management Tool

Imagine a project management tool where teams collaborate on various projects. Entities like "Teams", "Projects", and "Tasks" play central roles, showcasing ReBAC's adaptability:

1. Team Entities:

• Teams: Represent collaborative groups within the project management tool.
• Projects: Encompass various ongoing initiatives.
• Tasks: Break down project activities into manageable tasks.

2. Permissions Dynamics:

Team Leadership Permissions:

• "Team#Lead" designates team leadership, allowing leaders to manage team-related activities.

Project Ownership Permissions:

• "Project#Owner" signifies ownership at the project level, granting comprehensive control over project-related actions.

Task Assignment Permissions:

• "Task#Assignee" designates individuals responsible for specific tasks.

Project Management Tool Entities

These real-world scenarios demonstrate ReBAC's versatility and effectiveness in managing access control in different settings.

Advantages of ReBAC

Now, let's understand why Relationship-Based Access Control (ReBAC) stands out from traditional methods like Role-Based Access Control (RBAC) and Attribute-Based Access Control (ABAC). ReBAC brings a host of benefits to the table, enhancing scalability, flexibility, and adaptability in complex organizational setups. Let's take a closer look at its key advantages:

Granular and Contextual Control

ReBAC allows organizations to define granular access controls tailored to the specific relationships between users, resources, and entities. This ensures that permissions are contextually relevant, providing a nuanced level of control.

Efficient Management of Hierarchies

In scenarios with hierarchical structures, ReBAC simplifies the management of access control. By allowing permissions to be inherited based on relationships, it reduces the need for manual role assignments.

This simplifies the creation of natural connections between different business units, resources, and entities, making it easier to navigate complex hierarchies.

Scalability and Adaptability

ReBAC is designed to scale with organizational growth and changes in relationships. It easily accommodates the introduction of new entities or connections. However, it's crucial to address the challenge of role explosion, where the number of roles grows exponentially alongside asset growth.

Without proper management, this can lead to security risks and administrative overhead. Yet, ReBAC's scalability ensures that access controls remain effective, mitigating these challenges and avoiding the need for extensive modifications.

With these advantages in mind, ReBAC offers a robust framework for access control that meets the evolving needs of modern organizations. Now, let's delve into the common Relationship Type Permission Models to further understand how ReBAC operates.

Common Relationship Type Permission Models

Let’s look at the some of the permission models:

Ownership Model

The Ownership Model in ReBAC is a fundamental concept where ownership relationships streamline authorization within hierarchical structures.

In this model, the act of owning a higher-level entity automatically extends ownership over its subordinate entities.

Imagine a scenario in a cloud storage platform where users create folders to organize their files. In the Ownership Model, the user who creates a folder is designated as the owner.

Consequently, this ownership relation automatically grants the user ownership permissions for all files within that folder.

This hierarchical ownership structure simplifies permission management and mirrors real-world ownership dynamics.

Parent-Child & Hierarchical Model

The Parent-Child & Hierarchical Model is a powerful tool for managing access control in hierarchical structures such as organizational frameworks or file systems.

In this model, permissions granted at the parent level down to its child entities, ensuring a cohesive and efficient authorization system.

Consider a corporate environment where organizations have multiple departments. Using ReBAC's Parent-Child & Hierarchical Model, permissions granted at the organization level, such as admin privileges, seamlessly extend to the organization's departments and their respective members.

This hierarchical flow of permissions reflects the organizational structure, making it easy to manage access control across different levels.

User Groups & Teams Model

The User Groups & Teams Model allows for efficient permission management by grouping users based on shared attributes or project affiliations.

In this model, permissions assigned to a group leader, for instance, can be effortlessly applied to all members of that group.

In a collaborative project management tool, teams serve as user groups. Applying ReBAC's User Groups & Teams Model, the team lead's permissions, like editing or deleting project tasks, can be automatically inherited by all team members.

This streamlined approach simplifies access control in collaborative environments, where team-based permissions are crucial for project efficiency.

These three Relationship-Based Access Control models demonstrate the flexibility and adaptability of ReBAC in handling diverse organizational structures and application domains.

By aligning permissions with inherent relationships among entities, ReBAC provides an intuitive and powerful access control framework.

How to Implement ReBAC with Permify

Now, let's practically implement ReBAC using Permify.

Permify is an open-source authorization as a service platform that allows developers to model, manage, and enforce access control in applications. It provides tools for defining complex authorization rules and relationships between entities, such as users, organizations, and resources.

Permify uses a domain-specific language for creating authorization models and offers a Playground environment for testing these models.

It also supports the creation of relational tuples and attributes for managing dynamic access control scenarios, streamlining the process of implementing robust and flexible authorization systems in software applications.

We'll create a scenario covering both Ownership and Parent-Child & Hierarchical models.

We'll use the Permify Playground for modeling.

Modeling

Modeling in Permify involves creating a schema that defines the relationships and permissions between different entities in your system.

Here's a simplified process:

1. Define Entities: Start by creating entities that represent the resources in your system (for example: users, organizations, teams).
2. Define Relations: Establish relationships between these entities. For example, an organization can have members and admins, or a team can be part of an organization.
3. Define Actions and Permissions: Specify the actions that can be performed on each entity and the conditions under which they are allowed. For example, only admins can delete an organization.

Permify uses its own language for modeling authorization logic, allowing for complex structures using set-algebraic operators. The modeling process includes defining entities, relations, actions, permissions, and, if needed, attributes for more advanced scenarios like ABAC (Attribute-Based Access Control).

Modeling in Permify is about creating a clear blueprint of your organization's structure and defining who gets to do what.

Let's break down how to model a schema in Permify.

Step 1: Define Entities

Entities are the core objects in your model. In this case, we have user, organization, department, project, file, and task.

entity user {}
entity organization {}
entity department {}
entity project {}
entity file {}
entity task {}

Step 2: Establish Relationships

Next, we specify relationships between these entities. This defines how they are connected.

Organization:

• Has admin who are users.

entity organization {
    relation admin @user
}

Department:

• Belongs to an organization (parent).
• Has head, manager, and employee roles, all of which are users.

entity department {
    relation parent @organization
    relation head @user
    relation manager @user
    relation employee @user
}

Project:

• Belongs to a department (parent).

entity project {
    relation parent @department
}

File:

• Belongs to a department (parent).
• Has an owner who is a user.

entity file {
    relation parent @department
    relation owner @user
}

Task:

• Belongs to a project (parent).
• Has an assignee who is a user.

entity task {
    relation parent @project
    relation assignee @user
}

Step 3: Define Permissions

Permissions determine what actions specific roles can perform on each entity.

Project:

• contribute_to_project permission is granted to employee or manager of the parent department.

entity project {
    // ... (existing relations)
    permission contribute_to_project = parent.employee or parent.manager
}

File:

• read, edit, and delete permissions are controlled based on the manager of the parent department and the owner.

entity file {
    // ... (existing relations)
    permission read   = parent.manager or owner
    permission edit   = parent.manager or owner
    permission delete = owner
}

Task:

• view_task permission is given to the assignee.

entity task {
    // ... (existing relations)
    permission view_task = assignee
}

Full Schema:

// Define entities
entity user {}

entity organization {
    // Organizational roles
    relation admin @user
}

entity department {
    // Department roles
    relation parent @organization
    relation head @user
    relation manager @user
    relation employee @user
}

entity project {
    // Project roles
    relation parent @department

    // Permissions
    permission contribute_to_project = parent.employee or parent.manager
}

entity file {
    // Represents files' parent entity (department)
    relation parent @department

    // Represents the owner of the file
    relation owner @user

    // Permissions
    permission read   = parent.manager or owner
    permission edit   = parent.manager or owner
    permission delete = owner
}

entity task {
    // Represents tasks' parent entity (project)
    relation parent @project

    // Represents the assignee of the task
    relation assignee @user

    // Permissions
    permission view_task   = assignee
}

Relation Tuples

The creation of relation tuples for the organization schema can be accomplished through the Permify Playground and API.

Here's how the relationship tuples would be structured according to the schema:

User and Organization Relationships:

• For assigning a user as an admin in an organization, the tuple would be: organization:ID#admin@user:ID.
• To denote a user as a member of an organization: organization:ID#member@user:ID.

User and Department Relationships:

• Assigning a head to a department: department:ID#head@user:ID.
• Assigning a manager to a department: department:ID#manager@user:ID.
• Associating an employee with a department: department:ID#employee@user:ID.
• To set a department's parent organization: department:ID#parent@organization:ID.

Project and Department Relationships:

• To define the parent department of a project: project:ID#parent@department:ID.

File Management:

• Associating a file with its parent department: file:ID#parent@department:ID.
• Defining the owner of a file: file:ID#owner@user:ID.

Task Management:

• Linking a task to its parent project: task:ID#parent@project:ID.
• Assigning a user as the assignee of a task: task:ID#assignee@user:ID.

In each of these tuples, ID is a placeholder that should be replaced with the actual identifier of the entity or user in your system.

For instance, if you have an organization with an ID of 1 and a user with an ID of 3, and you want to assign this user as an admin of that organization, the tuple would be organization:1#admin@user:3.

Relationships dashboard

These tuples are created and managed using the Permify API. The API allows for creating, updating, and deleting these tuples as needed, reflecting the dynamic nature of relationships and permissions in an organization. This flexibility ensures that your authorization data is always up-to-date and consistent with the current state of your system's entities and their relationships.

Enforcement

To enforce access control in your schema using Permify, you can create scenarios in the Permify Playground's Enforcement section. This is done using YAML to define various test scenarios.

Here's an example based on your schema and the created relation tuples:

Check if a user (for example: user:2) can contribute to a project:

• Entity: project:1
• Subject: user:2
• Assertion: contribute_to_project: true or false (depending on whether user:2 is an employee or manager in the parent department of project:1).

- name: user_access_test
  checks:
    - entity: project:1
      subject: user:2
      context: null
      assertions:
        contribute_to_project: false
  entity_filters: []
  subject_filters: []

Check if a user (for example: user:4) can view a task:

• Entity: task:1
• Subject: user:4
• Assertion: view_task: true or false (true if user:4 is the assignee of the task).

- name: user_access_test
  checks:
    - entity: task:1
      subject: user:4
      context: null
      assertions:
        view_task: false
  entity_filters: []
  subject_filters: []

These scenarios will help you validate the permissions as per your schema in a controlled environment.

Each assertion in the YAML scenario will define the expected outcome (true or false) for a particular action or permission based on your schema and data tuples.

YAML representation

For detailed steps and examples, refer to the Permify Modeling Documentation.

Conclusion

By following these steps, you can effectively implement a sophisticated ReBAC system using Permify.

This implementation will provide a robust, flexible, and secure access control framework tailored to the unique needs and relationships within your organization.

You'll start by learning what authentication and authorization are, and then learn how to implement authentication in your applications using Supabase auth.

Table of Contents

• Prerequisites
• What Is Authentication and Authorization?
• How Does Authentication Work?
• Session Management with Tokens, Secrets, and Cookies
• Types of Authentication Factors
• Common Authentication Strategies
  • Password-based Authentication
  • Password-less Authentication
  • Two-Factor Authentication (2FA)
  • Multi-Factor Authentication (MFA)
  • OAuth 2.0 and Social Authentication
  • SSO and SAML
• Authentication and Security
• Supabase and Supabase Authentication Service
• How to use Supabase Auth
  • The API
  • SDKs
  • Auth UI Helpers

• Summary
• Resources

Prerequisites

You'll need the following to make the most out of this article:

• Basic programming knowledge.
• A Supabase project to follow along.
• And a text editor to try out the example code snippets.

What Is Authentication and Authorization?

In simple terms, authentication is the process of a user identifying themselves to a system and the system confirming that the user is who they claim to be.

On the other hand, authorization is the process of the system determining which parts of the application the user is allowed to view or interact with, and which parts the user is not allowed to access.

How Does Authentication Work?

A flowchart depicting the user authentication process

The first time a user interacts with a system, they will be requested to register. Typically, the user will provide a piece of information and a secret that is meant to be known only by them and the system. This is the registration part of the authentication process.

The next time the user interacts with the same system, they will be required to provide the identifying information along with the previously defined secret in order to verify their identity.

The device the user initiates the interaction from is the client and the system is the server. Once the system verifies the user, it sends over some information to the client about the user.

Because this process takes time and requires some action from the user, the client will store this information and send it back to the system whenever the user needs to access the system. This reduces friction by not requiring the user to actively re-authenticate every single time. This creates a user session.

Session Management with Tokens, Secrets, and Cookies

A sequence diagram showing session management in a client-server architecture

The server can pass the user's information to the client in two ways – through tokens or session ids.

In the case of tokens, the server generates a signed token and passes it to the client. This token is typically a JWT and may contain information regarding the user. The client will store this token and send it back to the server every time the user makes a request.

The server is able to verify the integrity of the token because it signed it. This is referred to as stateless authentication because the token is self contained and the server does not need to store session data in a database or cache.

In the case of cookies, the server creates a record of the user session in a database or a cache that will include a session ID. The server send this session ID to the client.

The client stores this session ID in a cookie and sends it back to the server whenever the user makes a request. The session ID is a random string that acts as pointer to the actual user record in the database.

When the server receives this cookie, it matches the session ID it contains to its session records, and then matches that record to the user data in the database. This is referred to as stateful authentication because a database look-up is needed.

Types of Authentication Factors

An authentication factor refers to a type of credential that can be used to verify a user's identity. There are 3 factors typically used in the authentication process, and they are:

1. Something you know: an examples is a password.
2. Something you have: an example is a token sent to your phone.
3. Something you are: an example is your fingerprint.

Common Authentication Strategies

Authentication strategies refer to the processes used to verify a user. Different types of authentication strategies include:

Password-based Authentication

This refers to the traditional way of users identifying themselves by providing a text-based secret that is user defined. Typically, the system handles the entire process on its servers and is responsible for security and reliability.

Password-less Authentication

In this approach, the system verifies the user’s identity without requiring user defined passwords. The system will, instead, generate a one time password (OTP) and send to the user. This OTP is then used in place of a password to gain access to the system. Examples include magic links, where the system sends a code to the user’s email.

Two-Factor Authentication (2FA)

The system attempts to verify the user is who they claim to be by requiring an extra piece of information after the primary authentication has checked out.

This can be an OTP sent to the user via email or SMS, or it can be by requiring the users' biometric information before the system grants access.

Multi-Factor Authentication (MFA)

This is similar to 2FA, except that the system will use more than one extra method to verify the user’s identity. The extra methods or factors used in both MFA and 2FA are usually external to the system, such as an SMS requiring a phone.

OAuth 2.0 and Social Authentication

OAuth is an authorization framework that allows clients to access information from an external server on the user's behalf. The external server prompts the user for permission to share the requested resources with the client.

After user permits the action, the external server issues an access token to the client.

The client then gives this access token to the original server, which verifies the token's validity and manages access to the requested resources. OAuth 2.0 is the latest version of OAuth and is the more widely used framework.

OAuth 2.0 extends support for non-browser based systems. Social Authentication is based on OAuth 2.0 but in this case, the external server that the client redirects the user to is typically a social media platform. This is the type of authentication process carried out whenever you see a "Continue with Twitter/X" button on an authentication page.

SSO and SAML

SAML stands for Security Assertion Markup Language. It is a standard for passing authentication and authorization information between systems. One system acts as the requesting system or the service provider (SP) and the other system holds the requested information or acts as the Identity Provider (IdP).

On receiving this request, the identity provider will generate some statements in SAML form that contains some user information. The service provider then uses this information to decide how to handle the user in relation with its protected resources.

SSO refers to Single Sign On. This is an authentication strategy that lets users sign in through one system/application that then lets them access multiple applications within the same network.

This improves the user experience by not requiring the user to log in to different related applications. An example of this is Google workspace. You don't need to log into Docs separately if you are already logged into your Gmail account. SSO is facilitated by SAML as SAML provides a standard authentication mechanism and allows different systems to trust each other.

Authentication and Security

Authentication involves handling, moving, and storing sensitive user information in relation to protected server resources. This makes security and best practices an important aspect of an authentication system.

There are some basic steps you can take to greatly increase the security of your authentication systems. These include:

• Enforcing stronger passwords.
• Requiring the user to register an extra factor to enable 2FA.
• Encrypting sensitive data as it is being transferred via HTTPS.
• Storing passwords in an encrypted manner.
• Using standard authentication frameworks like OAuth 2.0.

There are certain compliances that your system should consider when handling sensitive user data beyond specific authentication information. This is even more so if operating in certain countries or handling enterprise applications. These compliances include:

• GDPR: This compliance enforces standards around data handling including confidentiality and integrity.
• HIPAA: This compliance applies to medical data. It expects high levels of integrity.
• SOC: This is a framework more generally required of cloud technologies. It is based on the American Institute of CPAs and covers aspects of privacy, security, availability, integrity and confidentiality.

Keeping all this in mind, you will find that it is often easier to use dedicated authentication services for your applications instead of rolling out your own auth.

There are lots of options for this, including dedicated authentication services such as Clerk and Auth0, and Backend-as-a-Service such as Supabase and Firebase. In this case, let's take a look at the Supabase authentication offering.

Supabase and Supabase Authentication Service

Supabase is an open source Backend as a Service (BaaS) platform that makes developing a backend for your applications very easy and fast. It is based on open source technologies and actively supports the open source ecosystem.

Supabase offers common services that most backend applications will require. These services are:

• Database: This is a fully featured Postgres database.
• Authentication: This is an enterprise ready authentication service that is based on a fork of the goTrue server.
• Realtime: This is an API that adds the ability to use real-time capabilities in your applications.
• Storage: This is a storage service which is an s3 wrapper.
• Edge Functions: These are serverless functions that run on the edge. Powered by the Deno runtime.
• Vector: This is a vector database that makes it easier to work with embeddings in your AI applications.

Supabase is SOC2, HIPAA and GDPR compliant, self-host-able and open source. Furthermore, their authentication service exposes many strategies, giving you full control over your data and can be used independently of their other offerings. This and their auto documenting API makes it a very good choice for your applications.

How to use Supabase Auth

The first step is to set up your Supabase project's auth settings. You can enable the exact authentication methods you want to use via the settings. There are three ways you can start using Supabase auth in your project:

The API

You can directly use the authentication service in your applications by calling the auth endpoint and passing the user information to it. You can also get, update and delete your users.

The API is automatically available when you create a project via the Supabase console and can be called like so:

//This will return an object containing an access token, the newly created user data and other metadata
const res = await fetch("https://<your-project-ref>/auth/v1/signup", {
  method: "POST",
  headers: {
    authorization: "Bearer YOUR_SUPABASE_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    email: "user-email",
    password: "user-password",
  }),
});

SDKs

Supabase offers a few SDKs (software development kits) in different programming languages meant to make interacting with your Supabase project straightforward. Languages officially supported include Dart and JavaScript, with Python and others having strong community support.

The procedure for getting started involves adding the SDK as a dependency, then connecting your application to your Supabase project.

In the case of the JavaScript SDK, this would look something like this:

//Install via npm:
npm install @supabase/supabase-js

// or add cdn links: 
<script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>

//Then initialize 
Supabaseimport { createClient } from '@supabase/supabase-js'

const supabaseUrl = 'https://<your-project-ref>.supabase.co'
const supabaseKey = process.env.SUPABASE_ANON_KEY
const supabase = createClient(supabaseUrl, supabaseKey)

Then you can access the authentication methods under the auth namespace like so:

const { data, error } = await supabase.auth.signUp({
  email: 'user email',
  password: 'user password',
})

Auth UI Helpers

Supabase provides helper libraries to make authentication using their service even easier. These libraries provide customizable login screens that support magic links, password based and social login strategies.

Currently, the libraries are available for JavaScript and Flutter. Supabase also provides a separate SSR (Server Side Rendering) package for applications that use server side frameworks and require a Supabase access token to be available to them.

To start using React Auth UI, as an example, first you need to install the dependencies as shown below:

npm install @supabase/supabase-js @supabase/auth-ui-react 
@supabase/auth-ui-shared

Then you can start using the library after initializing Supabase as in the SDK example above. Here is some sample code that shows how to use the auth UI library in a React application:

import { useEffect } from "react";
import { useNavigate } from "react-router-dom";
import { Auth } from "@supabase/auth-ui-react";
import { ThemeSupa } from "@supabase/auth-ui-shared";
import { supa } from "../constants";

const AuthUi = () => {
  const navigate = useNavigate();

  useEffect(() => {
    const {
      data: { subscription },
    } = supa.auth.onAuthStateChange((event) => {
      if (event === "SIGNED_IN") {
        navigate("/authenticated");
      }
    });

    return () => subscription.unsubscribe();
  }, [navigate]);

  return (
    <Auth
      supabaseClient={supa}
      providers={["google", "github", "apple", "discord"]}
      // controls whether to display only social providers
      // onlyThirdPartyProviders
      redirectTo="http://localhost:3000/authenticated"
      // comes with preconfigured themes, can add custom themes
      appearance={{ theme: ThemeSupa }}
      // controls how to display the social provider icons
      socialLayout="horizontal"
    />
  );
};

export default AuthUi;

This would display the following form on screen:

Summary

Authentication is the process of the user identifying themselves and the server verifying this identity while authorization is the system determining what access the user should have to the resources and limiting the user accordingly.

After the server authenticates the user, it will pass the user information in the form of either a token or session ID within a cookie.

The information will be passed back and forth between the client and server whenever the user needs certain access until they expire or the user terminates the cycle by logging out or deleting their account.

This process of user verification occurs by employing certain factors of authentication. For example, one system may only require a password while another requires a password and a code sent to the users phone number.

Your authentication system can allow multiple strategies of authentication using any of the three auth factors.

Supabase is an excellent option if you opt not to handle your own auth.

Supabase auth can be accessed via the API, the SDKs and the Auth libraries. Supabase maintains an SSR package for server side frameworks.

Resources

The following resources are helpful further reading. They offer more explanations on authentication and authorization, as well as Supabase specific documentation.

• An indepth explanation of OAuth
• Supabase security
• Supabase docs on authentication
• Auth UI docs page
• Supabase on auth helpers and SSR
• On SSO, SAML and enterprise auth

MongoDB, Express, React, and Node.js are the components of the MERN stack, one of the most widely used web development stacks out there today.

The MERN stack enables programmers to create dependable web applications with strong capabilities. Yet, security should be a key concern with any web application.

User authentication and permissions are some of the most important security features of any web service. In order to protect sensitive information and stop unauthorized access to important functions, these make sure that only authorized users can access certain areas of the application.

By the end of this article, you will have a firm grasp on how to integrate JWT (Json Web Token)-based user authentication and authorization into your MERN stack web application.

Here's what we'll cover:

• What is User Authentication & Authorization?
• What is the MERN Stack?
• Why Use the MERN Stack?
• How to Set Up the Project Environment
• How to Create a New React Application
• Node.js and Express.js Installation and Configuration
• How to Set Up MongoDB
• How to Implement the Backend
• How to Handle the SIGNUP Route
• How to Handle the LOGIN Route
• How to Handle the HOME Route
• How to Implement the Frontend
• How to Handle the Signup Logic
• How to Handle the Login Logic
• How to Handle the Home Page Logic
• Conclusion

What is User Authentication & Authorization?

In application security, authentication and authorization are two crucial ideas that work together to guarantee access to the resources of an application.

Many people frequently confuse these words – but after reading this guide, will we? NOT AGAIN!

Authentication

Verifying a user's or an entity's identity is the process called Authentication. It entails validating the user's credentials, such as a username and password, to ensure that the user is who they claim to be.

Authorization

The process of authorizing or refusing access to particular resources or functions within an application is known as Authorization. Once a user has been verified as authentic, the program checks their level of authorization to decide which areas of the application they can access.

Authentication is comparable to when a college applicant is admitted to a program based on the results of a written exam. The student is permitted on school grounds, but is not permitted in a department or class that is not their own (that was not given to them during admission). This action is known as Authorization.

What is the MERN Stack?

Let's talk about the various elements of the MERN stack before we start creating the authentication mechanism.

1. MongoDB is a NoSQL database that uses dynamic schemas and documents that resemble JSON to store data. MongoDB is a popular option for creating scalable web applications because it is effective at managing big amounts of data.
2. Express.js is a Node.js web application framework that offers a selection of functionality for creating online applications. Express.js is a well-liked option for developing online applications since it is compact, quick, and simple to use.
3. React.js is a JavaScript library used to create user interfaces. By disassembling complicated user interfaces into smaller, reusable components, React.js offers a declarative method for doing so.
4. Node.js is based on the V8 JavaScript engine in Chrome, and is a JavaScript runtime. The ability to run JavaScript on the server-side makes Node.js the perfect platform for creating web applications.

Why Use the MERN Stack?

The MERN stack is a great option for developing web applications since it includes all of the technologies needed to create a cutting-edge, scalable online application.

Following a discussion of the various elements of the MERN stack, we will use code snippets to develop a whole user authentication system from scratch.

How to Set Up the Project Environment

To get started with building the authentication system, we first need to set up the project. We will create a new React application using create-react-app and install the required dependencies. We will also set up MongoDB and configure our Node.js server.

NB: In this article, we will be making use of Visual studio code editor, which I highly recommend.

Before we dive into this, you're going to create a folder which will contain other sub folders as you move on in this article.

After creating your folder, it should look like the image below:

The folder you just created will contain two sub folders called the client and server. Run the commands below in your terminal to create the sub folders:

mkdir client

This will create the client sub folder.

mkdir server

This will create the server sub folder. Your application folder should look like this:

How to Create a New React Application

You can create a new React application using create-react-app. Open your terminal and run the below command to create a new React application.

But first, you will need to go into the client folder using cd client, then run the following command:

npx create-react-app

After the command above has successfully created the app, type npm start in your terminal. Make sure you're in your client directory. Your output should look like the image below:

Before we move to the server directory, you will need to remove some boilerplate in your React application. Your client should look like the image below;

Once you're done with the above, restart your React application by running npm start in your terminal. Your application should be looking like this:

Now, you've successfully setup your client side of the application 😊 yeah!

Node.js and Express.js Installation and Configuration

To setup your backend application, run mkdir server in your terminal to get into the server sub folder. After getting into the server sub folder, run the following command to initialize the backend application:

npm init --yes

The npm init --yes command in Node.js creates a new package.json file for a project with default settings, without asking the user any questions.

The --yes or -y flag tells npm to use default values for all prompts that would normally appear during the initialization process.

The server folder should now contain a package.json file just like so:

{
  "name": "server",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

To install Express.js and other dependencies, run the following commands in your terminal:

 npm install express cors bcrypt cookie-parser nodemon jsonwebtoken mongoose dotenv

The above commands install the following dependencies:

• Express.js, which is our Node.js web application framework.
• bcrypt, which helps us hash the user's password.
• cookie-parser is the the cookie-parser middleware that handles cookie-based sessions. It extracts information from cookies that may be required for authentication or other purposes.
• nodemon is a tool used to automatically restart a Node.js application whenever changes are made to the code.
• CORS is a middleware used to enable Cross-Origin Resource Sharing (CORS) for an Express.js application.
• jsonwebtoken helps us create and verify JSON Web Tokens.
• dotenv allows you to store configuration data in a .env file, which is typically not committed to version control, to separate sensitive information from your codebase. This file contains key-value pairs that represent the environment variables.

After installing the required dependencies, create a new file called index.js in the root directory of your server sub folder of your application. The index.js file will contain our Node.js server.

In the index.js file of your server, add the following code:

const express = require("express");

const app = express();
const PORT = 4000;

app.listen(PORT, () => {
  console.log(`Server is listening on port ${PORT}`);
});

Before you start the server, update your package.json file in the server by adding the code below:

  "scripts":{
  start: "nodemon index.js",
  test: 'echo "Error: no test specified" && exit 1',
};

This will make sure your application restarts on any update. Now, you can start your server by running npm start in your terminal.

If all these are successfully executed, your terminal should look like this:

How to Set Up MongoDB

You're almost done with setting up your application. If you do not have mongodb installed your computer, follow these steps.

Now, I assume you have successfully installed mongodb on your computer. To link your database to your backend, follow the procedures below.

STEP 1: Go into your MongoDB cloud clusters, which should look like the image below:

STEP 2: Click on the Database Access, which is on the left of the sidebar. Click on ADD NEW DATABASE USER which will pop up a modal, like the image below:

STEP 3: Fill out the Password Authentication with your desired username and password for the database of this particular project.

STEP 4: Before saving this, click the Built-in Role dropdown, and select Read and write to any database. Now, go ahead to click Add user.

STEP 5: Click on Database, and on the left side of the sidebar, click the connect button, which is beside View Monitoring. A modal popup will be displayed, then click connect your application and copy the code snippet you find there.

You will replace <username> and <password> with the username and password you created in STEP 3 in your index.js file in the server folder.

Before going into your index.js file, you will create a .env file in your server directory, which will contain your MONGODB_URL, PORT, database_name, and database_password like the code below:

MONGO_URL =
  "mongodb+srv://database_name:database_password@cluster0.fbx6x.mongodb.net/?retryWrites=true&w=majority";
PORT = 4000;

Once you're done with this, go into your index.js in your server directory, and update it with the code below:

const express = require("express");
const mongoose = require("mongoose");
const cors = require("cors");
const app = express();
require("dotenv").config();
const { MONGO_URL, PORT } = process.env;

mongoose
  .connect(MONGO_URL, {
    useNewUrlParser: true,
    useUnifiedTopology: true,
  })
  .then(() => console.log("MongoDB is  connected successfully"))
  .catch((err) => console.error(err));

app.listen(PORT, () => {
  console.log(`Server is listening on port ${PORT}`);
});

app.use(
  cors({
    origin: ["http://localhost:4000"],
    methods: ["GET", "POST", "PUT", "DELETE"],
    credentials: true,
  })
);

app.use(express.json());

In the code above, we are configuring our application to be able to have access to the .env file. You can get the information in your .env file by doing process.env.

So you're destructing the values from the .env file by doing process.env so you don't repeat yourself (DRY) which is a good engineering practice.

• CORS (Cross origin resource sharing): You can allow requests from other domains to access the resources on your server by using the cors() express middleware function. The CORS headers that your server should include in the response can be specified using the function's optional configuration object parameter, which is taken as a parameter by the function which is the origin, methods and credentials.
• express.json(): The express.json() will add a body property to the request or req object. This includes the request body's parsed JSON data. req.body in your route handler function will allow you to access this data.
• useNewUrlParser: This property specifies that Mongoose should use the new URL parser to parse MongoDB connection strings. This is set to true by default.
• useUnifiedTopology: This property specifies that Mongoose should use the new Server Discovery and Monitoring engine. This is set to false by default.

After following the steps above, you will restart your application by doing npm start in your server directory. Your terminal should look like the image below;

How to Implement the Backend

Create the following folders in the server directory of your application after first ensuring that you are in that directory. Controllers, Middlewares, Routes, Models, and util are the names of these folders.

How to Handle the SIGNUP Route

Create a file called UserModel.js in the Models directory and put the following code into it to get started:

const mongoose = require("mongoose");
const bcrypt = require("bcryptjs");

const userSchema = new mongoose.Schema({
  email: {
    type: String,
    required: [true, "Your email address is required"],
    unique: true,
  },
  username: {
    type: String,
    required: [true, "Your username is required"],
  },
  password: {
    type: String,
    required: [true, "Your password is required"],
  },
  createdAt: {
    type: Date,
    default: new Date(),
  },
});

userSchema.pre("save", async function () {
  this.password = await bcrypt.hash(this.password, 12);
});

module.exports = mongoose.model("User", userSchema);

The user schema and user password will be created in the above code using mongoose and bcryptjs, respectively, for security purposes.

The password is hashed for security reasons prior to saving the user.

Next, you will setup a function to handle the generation of a atoken, which will be called SecretToken.js in the util folder. Copy and paste the code below into the newly created file (SecretToken.js):

require("dotenv").config();
const jwt = require("jsonwebtoken");

module.exports.createSecretToken = (id) => {
  return jwt.sign({ id }, process.env.TOKEN_KEY, {
    expiresIn: 3 * 24 * 60 * 60,
  });
};

Once that's done, create a file called AuthController.js in the Controllers directory and paste in the following code:

const User = require("../Models/UserModel");
const { createSecretToken } = require("../util/SecretToken");
const bcrypt = require("bcryptjs");

module.exports.Signup = async (req, res, next) => {
  try {
    const { email, password, username, createdAt } = req.body;
    const existingUser = await User.findOne({ email });
    if (existingUser) {
      return res.json({ message: "User already exists" });
    }
    const user = await User.create({ email, password, username, createdAt });
    const token = createSecretToken(user._id);
    res.cookie("token", token, {
      withCredentials: true,
      httpOnly: false,
    });
    res
      .status(201)
      .json({ message: "User signed in successfully", success: true, user });
    next();
  } catch (error) {
    console.error(error);
  }
};

The user's inputs are obtained from the req.body in the code above, and you then check the email to make sure no past registrations have been made. We'll use the values obtained from req.body to create the new user after that has occurred.

You don't need to worry about how the unique _id was obtained because MongoDB always assigns a new user with a unique _id

The newly formed user's _id is then supplied as an parameter to the createSecretToken() function, which handles token generation.

The cookie will be sent to the client with key of "token", and value of token.

Next, create a file called AuthRoute.js in the Routes directory. Paste the code below into the newly created file:

const { Signup } = require("../Controllers/AuthController");
const router = require("express").Router();

router.post("/signup", Signup);

module.exports = router;

In the code above, the /signup route has a post method attached to it, when it's been called, the Signup controller will be executed.

Next, update your index.js file so it can be aware of the routes. Your index.js file should look like the code below:

const express = require("express");
const mongoose = require("mongoose");
const cors = require("cors");
const app = express();
require("dotenv").config();
const cookieParser = require("cookie-parser");
const authRoute = require("./Routes/AuthRoute");
const { MONGO_URL, PORT } = process.env;

mongoose
  .connect(MONGO_URL, {
    useNewUrlParser: true,
    useUnifiedTopology: true,
  })
  .then(() => console.log("MongoDB is  connected successfully"))
  .catch((err) => console.error(err));

app.listen(PORT, () => {
  console.log(`Server is listening on port ${PORT}`);
});

app.use(
  cors({
    origin: ["http://localhost:3000"],
    methods: ["GET", "POST", "PUT", "DELETE"],
    credentials: true,
  })
);
app.use(cookieParser());

app.use(express.json());

app.use("/", authRoute);

The cookie-parser manages cookie-based sessions or extracts data from cookies. It's added to the code above along with the authRoute that the application will utilize.

Now, let's go ahead to test the /signup route with a tool called Postman. Make sure you're in the server directory in the terminal, then run npm start to start your application.

The image above shows the response gotten when a request is sent.

The image above shows the generated cookie from the response.

The image above illustrates what happens when you try to use a registered email.

By now, the user will be created in the database like the image below:

How to Handle the LOGIN Route

Open the AuthController.js file in the Controllers directory, and update it with the code below:

module.exports.Login = async (req, res, next) => {
  try {
    const { email, password } = req.body;
    if(!email || !password ){
      return res.json({message:'All fields are required'})
    }
    const user = await User.findOne({ email });
    if(!user){
      return res.json({message:'Incorrect password or email' }) 
    }
    const auth = await bcrypt.compare(password,user.password)
    if (!auth) {
      return res.json({message:'Incorrect password or email' }) 
    }
     const token = createSecretToken(user._id);
     res.cookie("token", token, {
       withCredentials: true,
       httpOnly: false,
     });
     res.status(201).json({ message: "User logged in successfully", success: true });
     next()
  } catch (error) {
    console.error(error);
  }
}

You are determining in the code above whether the email and password match any previously stored user in the database.

Then add the following code to the file AuthRoute.js in the Routes directory:

const { Signup, Login } = require('../Controllers/AuthController')
const router = require('express').Router()

router.post('/signup', Signup)
router.post('/login', Login)

module.exports = router

Now, let's go ahead to test the application:

If you try to use an unregistered email or password, you'll get the message below:

How to Handle the HOME Route

Now, you will create a AuthMiddleware.js file, in the Middlewares directory, and paste in the code below:

const User = require("../Models/UserModel");
require("dotenv").config();
const jwt = require("jsonwebtoken");

module.exports.userVerification = (req, res) => {
  const token = req.cookies.token
  if (!token) {
    return res.json({ status: false })
  }
  jwt.verify(token, process.env.TOKEN_KEY, async (err, data) => {
    if (err) {
     return res.json({ status: false })
    } else {
      const user = await User.findById(data.id)
      if (user) return res.json({ status: true, user: user.username })
      else return res.json({ status: false })
    }
  })
}

The code above checks if the user has access to the route by checking if the tokens match.

Next, update the AuthRoute.js file in the Routes directory with the code below:

router.post('/',userVerification)

Now, you can go ahead to test your route. It should look like the image below:

How to Implement the Frontend

To get started, go into the client directory and install the following in your terminal:

npm install react-cookie react-router-dom react-toastify axios

Now, update the index.js file in the client directory with the code snippet below:

In the code above, wrapping your App component with BrowserRouter is necessary to enable client-side routing and take advantage of its benefits in your application.

NB: Remove the React.StrictMode later when you are testing the application and your data is being fetched twice.

Also, import react-toastify so it can be available in your application.

Now, go ahead to create the pages directory in your client directory, which will contain the Home.jsx file, Login.jsx file, Signup.jsx and index.js to export the components. Your folder should look like the image below:

Now, fill the Login.jsx, Signup.jsx, and Home.jsx, respectively, with the code below. These snippets below, are functional components which will be modified later in this guide.

NB: This can be automatically generated by typing the shortcut rafce + enter in the file you want to add the snippet in your visual studio code editor. Make sure this extension is installed in your visual studio code for this to work.

Login.jsx:

import React from "react";

const Login = () => {
  return <h1>Login Page</h1>;
};

export default Login

Signup.jsx:

import React from "react";

const Signup = () => {
  return <h1>Signup Page</h1>;
};

export default Signup

Home.jsx:

import React from "react";

const Home = () => {
  return <h1>Home PAGE</h1>;
};

export default Home

After that's done, you will go into the index.js file in the pages directory to export the newly created components. It should look like the image below:

The method shown above makes importing components easier by requiring only one import line.

Now, update the App.js file in the src directory with the code below.

import { Route, Routes } from "react-router-dom";
import { Login, Signup } from "./pages";
import Home from "./pages/Home";

function App() {
  return (
    <div className="App">
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/login" element={<Login />} />
        <Route path="/signup" element={<Signup />} />
      </Routes>
    </div>
  );
}

export default App;

The routes will be made available in your application using the above code. The example below will help to clarify:

How to Handle the Signup Logic

In the Signup.jsx file in the pages directory, paste the following code snippet:

import React, { useState } from "react";
import { Link, useNavigate } from "react-router-dom";
import axios from "axios";
import { ToastContainer, toast } from "react-toastify";

const Signup = () => {
  const navigate = useNavigate();
  const [inputValue, setInputValue] = useState({
    email: "",
    password: "",
    username: "",
  });
  const { email, password, username } = inputValue;
  const handleOnChange = (e) => {
    const { name, value } = e.target;
    setInputValue({
      ...inputValue,
      [name]: value,
    });
  };

  const handleError = (err) =>
    toast.error(err, {
      position: "bottom-left",
    });
  const handleSuccess = (msg) =>
    toast.success(msg, {
      position: "bottom-right",
    });

  const handleSubmit = async (e) => {
    e.preventDefault();
    try {
      const { data } = await axios.post(
        "http://localhost:4000/signup",
        {
          ...inputValue,
        },
        { withCredentials: true }
      );
      const { success, message } = data;
      if (success) {
        handleSuccess(message);
        setTimeout(() => {
          navigate("/");
        }, 1000);
      } else {
        handleError(message);
      }
    } catch (error) {
      console.log(error);
    }
    setInputValue({
      ...inputValue,
      email: "",
      password: "",
      username: "",
    });
  };

  return (
    <div className="form_container">
      <h2>Signup Account</h2>
      <form onSubmit={handleSubmit}>
        <div>
          <label htmlFor="email">Email</label>
          <input
            type="email"
            name="email"
            value={email}
            placeholder="Enter your email"
            onChange={handleOnChange}
          />
        </div>
        <div>
          <label htmlFor="email">Username</label>
          <input
            type="text"
            name="username"
            value={username}
            placeholder="Enter your username"
            onChange={handleOnChange}
          />
        </div>
        <div>
          <label htmlFor="password">Password</label>
          <input
            type="password"
            name="password"
            value={password}
            placeholder="Enter your password"
            onChange={handleOnChange}
          />
        </div>
        <button type="submit">Submit</button>
        <span>
          Already have an account? <Link to={"/login"}>Login</Link>
        </span>
      </form>
      <ToastContainer />
    </div>
  );
};

export default Signup;

How to Handle the Login Logic

Add the following code snippet to the Login.jsx file in the pages directory:

import React, { useState } from "react";
import { Link, useNavigate } from "react-router-dom";
import axios from "axios";
import { ToastContainer, toast } from "react-toastify";

const Login = () => {
  const navigate = useNavigate();
  const [inputValue, setInputValue] = useState({
    email: "",
    password: "",
  });
  const { email, password } = inputValue;
  const handleOnChange = (e) => {
    const { name, value } = e.target;
    setInputValue({
      ...inputValue,
      [name]: value,
    });
  };

  const handleError = (err) =>
    toast.error(err, {
      position: "bottom-left",
    });
  const handleSuccess = (msg) =>
    toast.success(msg, {
      position: "bottom-left",
    });

  const handleSubmit = async (e) => {
    e.preventDefault();
    try {
      const { data } = await axios.post(
        "http://localhost:4000/login",
        {
          ...inputValue,
        },
        { withCredentials: true }
      );
      console.log(data);
      const { success, message } = data;
      if (success) {
        handleSuccess(message);
        setTimeout(() => {
          navigate("/");
        }, 1000);
      } else {
        handleError(message);
      }
    } catch (error) {
      console.log(error);
    }
    setInputValue({
      ...inputValue,
      email: "",
      password: "",
    });
  };

  return (
    <div className="form_container">
      <h2>Login Account</h2>
      <form onSubmit={handleSubmit}>
        <div>
          <label htmlFor="email">Email</label>
          <input
            type="email"
            name="email"
            value={email}
            placeholder="Enter your email"
            onChange={handleOnChange}
          />
        </div>
        <div>
          <label htmlFor="password">Password</label>
          <input
            type="password"
            name="password"
            value={password}
            placeholder="Enter your password"
            onChange={handleOnChange}
          />
        </div>
        <button type="submit">Submit</button>
        <span>
          Already have an account? <Link to={"/signup"}>Signup</Link>
        </span>
      </form>
      <ToastContainer />
    </div>
  );
};

export default Login;

How to Handle the Home Page Logic

Copy and paste the following code snippet into the Home.jsx file located in the pages directory:

import { useEffect, useState } from "react";
import { useNavigate } from "react-router-dom";
import { useCookies } from "react-cookie";
import axios from "axios";
import { ToastContainer, toast } from "react-toastify";

const Home = () => {
  const navigate = useNavigate();
  const [cookies, removeCookie] = useCookies([]);
  const [username, setUsername] = useState("");
  useEffect(() => {
    const verifyCookie = async () => {
      if (!cookies.token) {
        navigate("/login");
      }
      const { data } = await axios.post(
        "http://localhost:4000",
        {},
        { withCredentials: true }
      );
      const { status, user } = data;
      setUsername(user);
      return status
        ? toast(`Hello ${user}`, {
            position: "top-right",
          })
        : (removeCookie("token"), navigate("/login"));
    };
    verifyCookie();
  }, [cookies, navigate, removeCookie]);
  const Logout = () => {
    removeCookie("token");
    navigate("/signup");
  };
  return (
    <>
      <div className="home_page">
        <h4>
          {" "}
          Welcome <span>{username}</span>
        </h4>
        <button onClick={Logout}>LOGOUT</button>
      </div>
      <ToastContainer />
    </>
  );
};

export default Home;

Ensure that the styles below are copied into your index.css file:

*,
::before,
::after {
  box-sizing: border-box;
  padding: 0;
  margin: 0;
}

label {
  font-size: 1.2rem;
  color: #656262;
}

html,
body {
  height: 100%;
  width: 100%;
}

body {
  display: flex;
  justify-content: center;
  align-items: center;
  background: linear-gradient(
    90deg,
    rgba(2, 0, 36, 1) 0%,
    rgba(143, 187, 204, 1) 35%,
    rgba(0, 212, 255, 1) 100%
  );
  font-family: Verdana, Geneva, Tahoma, sans-serif;
}

.form_container {
  background-color: #fff;
  padding: 2rem 3rem;
  border-radius: 0.5rem;
  width: 100%;
  max-width: 400px;
  box-shadow: 8px 8px 24px 0px rgba(66, 68, 90, 1);
}

.form_container > h2 {
  margin-block: 1rem;
  padding-block: 0.6rem;
  color: rgba(0, 212, 255, 1);
}

.form_container > form {
  display: flex;
  flex-direction: column;
  gap: 1.4rem;
}

.form_container div {
  display: flex;
  flex-direction: column;
  gap: 0.3rem;
}

.form_container input {
  border: none;
  padding: 0.5rem;
  border-bottom: 1px solid gray;
  font-size: 1.1rem;
  outline: none;
}

.form_container input::placeholder {
  font-size: 0.9rem;
  font-style: italic;
}

.form_container button {
  background-color: rgba(0, 212, 255, 1);
  color: #fff;
  border: none;
  padding: 0.6rem;
  font-size: 1rem;
  cursor: pointer;
  border-radius: 0.3rem;
}

span a {
  text-decoration: none;
  color: rgba(0, 212, 255, 1);
}

.home_page {
  height: 100vh;
  width: 100vw;
  background: #000;
  color: white;
  display: flex;
  justify-content: center;
  align-items: center;
  text-transform: uppercase;
  font-size: 3rem;
  flex-direction: column;
  gap: 1rem;
}

.home_page span {
  color: rgba(0, 212, 255, 1);
}

.home_page button {
  background-color: rgb(27, 73, 83);
  color: #fff;
  cursor: pointer;
  padding: 1rem 3rem;
  font-size: 2rem;
  border-radius: 2rem;
  transition: ease-in 0.3s;
  border: none;
}

.home_page button:hover {
  background-color: rgba(0, 212, 255, 1);
}


@media only screen and (max-width: 1200px){
  .home_page{
    font-size: 1.5rem;
  }
  .home_page button {
    padding: 0.6rem 1rem;
    font-size: 1.5rem;
  }
}

I'll now quickly demonstrate everything you've learned in this article.

Conclusion

In this article, you've learned how to use JWT for authentication and authorization, helping you build secure Node.js applications.

This guide can help you guard against security threats and prevent unauthorized access by implementing strong authentication and authorization procedures.

This central access point to your application’s data raises the question: how can you provide access to the information to those who need it while denying access to unauthorized requests?

The industry has provided several protocols and best practices for securing APIs. Today we will focus on OAuth2, one of the most popular options for authorizing clients into our APIs.

But how do we implement OAuth2? There are two ways to go about it:

1. Do it yourself approach
2. Work with a safe 3rd party like Auth0

In this article, I will walk you through an implementation of OAuth2 for Python and Flask using Auth0 as our identity provider. But first, we are going to discuss the do-it-yourself approach.

Why Not Build Your Own Authentication and Authorization?

For a few years now, I wanted to give back to the community that helped me so much by teaching me programming and helping me progress in my search for knowledge. I always thought that a great way to contribute was by having my own blog, a thing that I tried more than a few times and failed.

But where did I fail? Instead of focusing on writing, I tried to build my own blog engine because it’s in my nature. It’s what developers do. They love to build.

But why do I mention that here? Because many fall into the same trap when building APIs. Let me explain with an example.

Bob is a great developer, and he has this great idea for a ToDo app that can be the next big thing. Bob is very aware that for a successful implementation, users can only access their own data.

Here is bob’s application timeline:

• Sprint 0: Research ideas and start prototyping
• Sprint 1: Build user table and login screen with API
• Sprint 2: Add password reset screens and build all email templates
• Sprint 3: Build, create and list ToDos screens
• Sprint 4: MVP goes live
• User feedback:
  • Some users can’t log in due to a bug
  • Some users feel unsafe without 2-factor authentication
  • Some users don’t want to get yet another password. They prefer single sign-on with Google or Facebook.
  • …

Let’s talk about what happened. Bob spent the first few sprints not building his app but building the basic blocks, like logging in and out functionality, email notifications, and so on. This valuable time could have been spent differently, but what happens next is more concerning.

Bob’s backlog starts to fill in. Now, he needs to improvise a 2-factor authentication method, add single sign-on, and more non-product-related functions that could potentially delay his product.

And there’s still a big question to be answered: did Bob implement all the security mechanisms correctly? A critical error could expose all the user’s information to outsiders.

What Bob did is what I did with my blog many times. Sometimes, it's helpful to rely on 3rd parties if we want to get things done right.

Today, hackers and attacks have become so sophisticated that security is not a trivial factor anymore. It is a complicated system on its own, and it is often best to leave its implementation to experts – not only so it’s done right, but also so we can focus on what matters: building our applications and APIs.

How to Set Up a Free Auth0 Identity Management Account

Auth0 is a leading authentication and authorization provider, but let’s see how it can help Bob (or you) build a better app:

1. It saves time
2. It’s secure
3. It has a free plan

Time to get practical. First, make sure you have an Auth0 account. If not, you can create one here for free.

Create a New Auth0 API

There is still one more thing we have to do before we start coding. Head over to the APIs section of your Auth0 dashboard and click on the “Create API” button. After that, fill in the form with your details. However, make sure you select RS256 as the Signing Algorithm.

Your form should look like the following:

Creating the API – image showing fields to fill out

The API details page opens after successfully creating an API. Keep that tab open, as it contains information we need to set up our application. If you close it, don’t worry, you can always access it again.

How to Bootstrap our Application

Because we will focus on the security aspects only, we will take a few shortcuts when building our demo API. However, when developing actual APIs, please follow best practices for Flask APIs.

Install the dependencies

First, install the following dependencies for setting up Flask and authenticating users.

pipenv install flask python-dotenv python-jose flask-cors six

Build the endpoints

Our API will be straightforward. It will consist of only three endpoints, all of which, for now, will be publicly accessible. However, we will fix that soon. Here are our endpoints:

• / (public endpoint)
• /user (requires a logged in user)
• /admin (only users of admin role)

Let’s get to it:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index_view():
    """
    Default endpoint, it is public and can be accessed by anyone
    """
    return jsonify(msg="Hello world!")

@app.route("/user")
def user_view():
    """
    User endpoint, can only be accessed by an authorized user
    """
    return jsonify(msg="Hello user!")

@app.route("/admin")
def admin_view():
    """
    Admin endpoint, can only be accessed by an admin
    """
    return jsonify(msg="Hello admin!")

Very simple right? Let’s run it:

~ pipenv run flask run
* Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

And if we access our endpoint:

~ curl -i http://localhost:5000
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 23
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:24:57 GMT

{"msg":"Hello world!"}

~ curl -i http://localhost:5000/user
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 22
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:25:42 GMT

{"msg":"Hello user!"}

~ curl -i http://localhost:5000/admin
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 23
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:26:18 GMT

{"msg":"Hello admin!"}

How to Secure the Endpoints

As we are using OAuth, we will authenticate requests by validating an access token in JWT format. We'll send it to the API on each request as part of the HTTP headers.

Auth0 configuration variables

As mentioned in the previous section, our API needs to be aware and will require information from our Auth0 dashboard. So head back to your API details page, and grab two different values.

First, the API Identifier:

This is the value required when the API is created. You can also get it from your API details page:

How to find the API identifier on the API details page

Next, Auth0 domain:

Unless you're using a custom domain, this value will be [TENANT_NAME].auth0.com, and you can grab it from the Test tab (make sure not to include https:// and the last forward slash /).

Getting the Auth0 domain

Next, pass those values into variables so they can be used in the validation functions.

AUTH0_DOMAIN = 'YOUR-AUTH0-DOMAIN'
API_IDENTIFIER = 'API-IDENTIFIER'
ALGORITHMS = ["RS256"]

Error methods

During this implementation, we will need a way to throw errors when authentication fails. So we will use the following helpers for those needs:

class AuthError(Exception):
    def __init__(self, error, status_code):
        self.error = error
        self.status_code = status_code

@app.errorhandler(AuthError)
def handle_auth_error(ex):
    response = jsonify(ex.error)
    response.status_code = ex.status_code
    return response

How to capture the JWT token

The first step to validate a user is to retrieve the JWT token from the HTTP headers. This is very simple, but there are a few things to keep in mind. Here is an example of it:

def get_token_auth_header():
    """
    Obtains the Access Token from the Authorization Header
    """
    auth = request.headers.get("Authorization", None)
    if not auth:
        raise AuthError({"code": "authorization_header_missing",
                        "description":
                            "Authorization header is expected"}, 401)

    parts = auth.split()

    if parts[0].lower() != "bearer":
        raise AuthError({"code": "invalid_header",
                        "description":
                            "Authorization header must start with"
                            " Bearer"}, 401)
    elif len(parts) == 1:
        raise AuthError({"code": "invalid_header",
                        "description": "Token not found"}, 401)
    elif len(parts) > 2:
        raise AuthError({"code": "invalid_header",
                        "description":
                            "Authorization header must be"
                            " Bearer token"}, 401)

    token = parts[1]
    return token

How to validate the token

Having a token passed to our API is a good sign, but it doesn’t mean that it is a valid client. We need to check the token signature.

Since the logic to require authentication can be used for more than one endpoint, it would be important to abstract it and make it easily accessible for developers to implement. The best way to do this is by using decorators.

def requires_auth(f):
    """
    Determines if the Access Token is valid
    """
    @wraps(f)
    def decorated(*args, **kwargs):
        token = get_token_auth_header()
        jsonurl = urlopen("https://"+AUTH0_DOMAIN+"/.well-known/jwks.json")
        jwks = json.loads(jsonurl.read())
        unverified_header = jwt.get_unverified_header(token)
        rsa_key = {}
        for key in jwks["keys"]:
            if key["kid"] == unverified_header["kid"]:
                rsa_key = {
                    "kty": key["kty"],
                    "kid": key["kid"],
                    "use": key["use"],
                    "n": key["n"],
                    "e": key["e"]
                }
        if rsa_key:
            try:
                payload = jwt.decode(
                    token,
                    rsa_key,
                    algorithms=ALGORITHMS,
                    audience=API_IDENTIFIER,
                    issuer="https://"+AUTH0_DOMAIN+"/"
                )
            except jwt.ExpiredSignatureError:
                raise AuthError({"code": "token_expired",
                                "description": "token is expired"}, 401)
            except jwt.JWTClaimsError:
                raise AuthError({"code": "invalid_claims",
                                "description":
                                    "incorrect claims,"
                                    "please check the audience and issuer"}, 401)
            except Exception:
                raise AuthError({"code": "invalid_header",
                                "description":
                                    "Unable to parse authentication"
                                    " token."}, 401)

            _request_ctx_stack.top.current_user = payload
            return f(*args, **kwargs)
        raise AuthError({"code": "invalid_header",
                        "description": "Unable to find appropriate key"}, 401)
    return decorated

The newly created requires_auth decorator, when applied to an endpoint, will automatically reject the request if no valid user can be authenticated.

How to require an authenticated request for an endpoint

We are ready to secure our endpoints, let’s update the user and admin endpoints to utilize our decorator.

@app.route("/user")
@requires_auth
def user_view():
    """
    User endpoint, can only be accessed by an authorized user
    """
    return jsonify(msg="Hello user!")

@app.route("/admin")
@requires_auth
def admin_view():
    """
    Admin endpoint, can only be accessed by an admin
    """
    return jsonify(msg="Hello admin!")

Our only change was adding @required_auth at the top of the declaration of each endpoint function, and with that we can test once again:

~ curl -i http://localhost:5000/user
HTTP/1.0 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 89
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:42:26 GMT

{"code":"authorization_header_missing","description":"Authorization header is expected"}

~ curl -i http://localhost:5000/admin
HTTP/1.0 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 89
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:42:42 GMT

{"code":"authorization_header_missing","description":"Authorization header is expected"}

As expected, we can’t access our endpoints as the authorization header is missing. But before we add one, let’s see if our public endpoint still works:

~ curl -i http://localhost:5000
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 23
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:43:55 GMT

{"msg":"Hello world!"}

Awesome, it works as expected.

How to test it out

For testing our newly secured endpoints, we need to get a valid access token that we can pass to the request. We can do that directly on the Test tab on the API details page, and it’s as simple as copying a value from the screen:

Copying the token for testing

Once we have the token we can change our curl request accordingly:

~ curl -i -H "Authorization: bearer [ACCESS_TOKEN]"  http://localhost:5000/user
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 22
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 22:17:06 GMT

{"msg":"Hello user!"}

Please remember to replace [ACCESS_TOKEN] with the value you copied from the dashboard.

It works! But we still have some work to do. Even though our /admin endpoint is secured, it can be accessed by any user:

~ curl -i -H "Authorization: bearer [ACCESS_TOKEN]"  http://localhost:5000/admin
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 23
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 22:21:09 GMT

{"msg":"Hello admin!"}

Role-based access control

For role-based access control there’s a few things we need to do:

1. Create permissions for the API
2. Enable adding permissions to the JWT for the API
3. Update the code
4. Test with users

The first 2 points are very well explained in the Auth0 docs, so just make sure you add the corresponding permissions on your API.

Next, we need to update the code. We need a function to check if a given permission exists in the access token and return True if it does and False if it does not:

def requires_scope(required_scope):
    """
    Determines if the required scope is present in the Access Token
    Args:
        required_scope (str): The scope required to access the resource
    """
    token = get_token_auth_header()
    unverified_claims = jwt.get_unverified_claims(token)
    if unverified_claims.get("scope"):
            token_scopes = unverified_claims["scope"].split()
            for token_scope in token_scopes:
                if token_scope == required_scope:
                    return True
    return False

And lastly, it can be used as follows:

@app.route("/admin")
@requires_auth
def admin_view():
    """
    Admin endpoint, can only be accessed by an admin
    """
    if requires_scope("read:admin"):
        return jsonify(msg="Hello admin!")

    raise AuthError({
        "code": "Unauthorized",
        "description": "You don't have access to this resource"
    }, 403)

Now, only users with the permission read:admin can access our admin endpoint.

In order to test your final implementation, you can follow the steps detailed on obtaining an access token for a given user.

You can also use the Auth0 Dashboard to test permissions, but that is outside the scope of this article. If you would like to learn more about it, read here.

Conclusion

Today we learned how to secure a Flask API. We explored the do-it-yourself path, and we built a secure API with three levels of access – public access, private access and privately-scoped access.

There’s so much more that Auth0 can do for your APIs and also for your client applications. Today we just scratched the surface, and it’s up to you and your team when working with real-life scenarios to explore all the potential of their services.

The full code is available on GitHub.

Thanks for reading! If you like my teaching style, you can Subscribe to my weekly newsletter for developers and builders and get a weekly email with relevant content.

If you've ever signed in to a site like freeCodeCamp with your Google or GitHub account, there's a good chance that you're already using a JWT.

In this article, we'll go over how JWTs are used, then dig into what JWTs are, and how they can securely transmit data through the signature and validation process.

How JWTs Are Used

JWTs are usually used to manage user sessions on a website. While they're an important part of the token based authentication process, JWTs themselves are used for authorization, not authentication.

Here's a good overview of how token based authentication works:

Source

When you sign in to a site with a username and password, or with a third party method like Google, you're proving who you are with those sensitive details or access. This process is called authentication.

Once you're signed in, the site's server sends back a JWT that allows you access to things like your settings page, shopping cart, and so on. This process is called authorization.

You send your JWT to the server with each request. When the server receives it, it generates a signature using some data from your JWT, verifies it, and if your JWT is valid, it sends back a response.

What are JWTs?

At their core, JWTs are just bits of encoded JSON data with a cryptographic signature at the end.

Here's an example of a JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlF1aW5jeSBMYXJzb24iLCJpYXQiOjE1MTYyMzkwMjJ9.WcPGXClpKD7Bc1C0CCDA1060E2GGlTfamrd8-W0ghBE

Each JWT is made up of three segments, each separated by a dot (.). These three segments are the header, payload, and signature.

If you copy and paste that JWT into the JWT.io Debugger, you can see the decoded versions of those three segments.

Header Segment

The header segment of a JWT contains information about the algorithm and token type.

Here's the header segment of the example JWT token above:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

The header segment is base 64 URL encoded, and decodes to the following JSON object:

{
  "alg": "HS256",
  "typ": "JWT"
}

"alg" is the type of algorithm used in the last segment, the cryptographic signature. In this case, the HMAC SHA256 algorithm is used, though RSA is also common.

"typ" is the type of token the segmented string is, which in this case is JWT.

Payload Segment

The payload segment of a JWT contains registered claims or identifying information, usually for a user.

Here's the payload segment of the example JWT token above:

eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlF1aW5jeSBMYXJzb24iLCJpYXQiOjE1MTYyMzkwMjJ9

The payload segment is also base 64 URL encoded, and decodes to the following JSON object:

{
  "sub": "1234567890",
  "name": "Quincy Larson",
  "iat": 1516239022
}

Since JWTs are usually used as part of the authentication method for sites, the payload segment usually contains identifying information for a user. These claims fall into three categories: registered, public, and private.

Registered claims are a set of predefined claims defined here that are optional, but recommended when using JWTs.

Public claims are optional claims, usually from the IANA JSON Web Token Registry.

Private claims are optional, and are any claims that don't fall under the registered or public claims categories.

"sub" is the subject of the JWT, and is usually a unique identifying string for a user in an application, usually an email address, username, or id. Subjects are registered claims.

"name" is the full name of the user who was issued the JWT, and is a public claim.

"iat" is the "issued at" date for the token, and is a registered claim.

Signature Segment

The signature segment of a JWT contains the cryptographic signature of the token.

Here's the signature segment of the example JWT token above:

WcPGXClpKD7Bc1C0CCDA1060E2GGlTfamrd8-W0ghBE

The signature segment is made up of the base 64 URL encoded header and payload segments, a secret (usually the contents of a key in a signing algorithm), and hashed using the algorithm defined in the header segment:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  your-256-bit-secret
)

The signature helps ensure that the data in the header and payload segments haven't been tampered with, and the JWT can be trusted.

However, it's important to note that the cryptographic signature at the end of the JWT is just for validation. It doesn't encrypt any data in the header or payload segments of the token. So you should never send sensitive information like a user's password in a JWT – everything in the header and payload can and should be public.

How to Validate JWT Signatures

The exact method for validating a signature depends on the algorithm defined in the header segment and used to generate the signature itself.

For the HS256 signing algorithm, a private key is shared between two entities, say your application's server and an authentication server. This private key is used both to generate signatures for outgoing JWTs, and to validate signatures from incoming JWTs.

When your authentication server receives an incoming JWT, it uses the incoming JWT's header and payload segments and the shared private key to generate a signature.

If the signature matches, then your application knows that the incoming JWT can be trusted.

Another popular signing algorithm is RS256, which uses public and private key pairs to validate signatures. This is similar to the system used for SSH and SSL.

If you'd like to read more about how RS256 works, check out this article:

Other Helpful Tutorials

If you'd like to learn more about JWTs and how to use them in applications, check out these tutorials:

Thanks for Reading

If you found this article on JWTs helpful, consider sharing it so more people can benefit from it.

Also, feel free to reach out on Twitter and let me know what you think.

The two keywords here are “who” and “permissions”. “Who” refers to a specific identity, which can be a user, group or role. “permissions” refer to the policies that are attached to an identity. These permissions either allow or deny access to a resource.

IAM is the AWS way of authenticating and authorising identities. Authentication is not, however, the same as authorisation. Authentication is concerned with the “who” while authorisation is concerned with the “permissions”.

The Difference Between Authentication and Authorisation

Authentication is when an identity proves it is what/who it says it is. Authorisation, on the other hand, is proving that you have the permissions to access a resource.

To fully understand the difference, consider the following analogy. You need to be both authenticated and authorised in order to board a flight. Authentication is done with your passport or ID, where it is checked to ensure that the photo in your passport matches your face. This proves that you are who you say you are.

After you have been authenticated, you need to prove that you have the permission to take a specific flight. This is done with your boarding pass.

Both authentication and authorisation need to be carried out before you can board a flight. Similarly, both need to be carried out before you can access AWS resources.

You can read more about authorisation vs authentication here.

Authentication & authorisation are not the same

IAM users, groups, and roles are concerned with authentication – that is, proving that you are who you say you are. They are like passports that get you through security in an airport.

Without a boarding pass however, you cannot board a plane. The IAM policy is like a boarding pass, in that it grants or denies access to specific resources.

What are IAM Users?

This is any identity (humans or an application) that requires long term access to AWS resources. These entities make requests to IAM to get authenticated before any interaction with AWS resources is allowed the happen.

Authentication is done using a username/password combination for humans accessing AWS through the console, or through access keys for an application or a human accessing AWS through the command line interface.

What are IAM Groups?

IAM users can be placed in an IAM group. IAM groups makes it easier to organise a large number IAM users and apply permissions on a group level instead of an individual level. This is because the latter does not scale for a large number of users.

Imagine you have a team that consists of developers, architects, admin staff, DevOps engineers, live support and testers. Each of these teams has 10 people, for a total of 60 people.

Instead of setting permission policies for 60 people individually, you can put IAM users into their respective groups and apply permissions on a group level. This makes it easier to organise permissions and also easier to scale as your team grows.

IAM groups can be created for separate teams

There are no login credentials for IAM groups. Also, a user can belong to multiple groups, so for example, an IAM user that is in the DevOps group can also be in the live support group. This maps neatly to the real world where a DevOps engineer can also be in live support.

What are IAM Roles?

IAM roles are used to grant temporary access to multiple identities. These identities could be humans external to AWS accessing your services, IAM users, or applications.

These identities assume the role temporarily, and any permission policies attached to the role are by proxy applied to the identity assuming that role.

IAM roles are important because AWS has hard limits on the number of IAM users (currently 5000).

Trust policies vs permission policies

IAM policies that are attached to roles come in two flavours – trust policy and permission policy.

The trust policy controls which identity (for example IAM users, AWS resources like EC2 instances, anonymous entities) can assume that role. Once a role is assumed by an identity, AWS issues it Temporary Security Credentials.

You can think of the trust policy as how AWS authenticates an IAM role to ensure that only the identity that is allowed to assume the role can assume the role – that is, that an identity has proved that it is who/what it says it is.

But there is a catch. With trust policies, this authentication only works for a period of time. Once that time has elapsed, the identity needs to re-authenticate and get new Temporary Security Credentials.

The permission policy is relatively straightforward: it defines the permissions that the role has, which, by proxy, defines the permissions that the identity assuming that role will have.

IAM roles are a relatively difficult concept to grasp, so if you don’t quite understand it yet, please read on and it will become clearer.

How IAM Policies Work

IAM Policies are attached to identities, so users, groups, or roles. IAM policies can also be attached to some AWS resources. These types of policies are called resource based policies.

IAM policies are JSON documents, consisting of one or more statements that grant or deny access to AWS resources.

The IAM policy below shows how permissions are granted to an identity to read and write from an S3 bucket.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ListObjectsInBucket",
            "Effect": "Allow",
            "Action": ["s3:ListBucket"],
            "Resource": ["arn:aws:s3:::bucket-name"]
        },
        {
            "Sid": "AllObjectActions",
            "Effect": "Allow",
            "Action": "s3:*Object",
            "Resource": ["arn:aws:s3:::bucket-name/*"]
        }
    ]
}

• Sid stands for statement ID, an optional field that lets the reader quickly identify what a statement does.

• Effect can be either allow or deny

• Action refers to what action are you trying to perform. Format is service:operation.

• Resource refers to which resource are you interacting with. Typically you'll use ARN (Amazon Resource Name) which uniquely identify AWS resources.

By default, all requests are implicitly denied unless a policy explicitly has an “allow” as is the case in the example above.

This principle of least privilege ensures that an identity cannot use a resource unless they are explicitly granted the permission to do so.

Bringing it All Together – How IAM Works

Consider a pizza restaurant. It will have some full time employees – like chefs, waiters and cleaners. It may also have some part time chefs to help during peak demand on evenings and weekends. If the restaurant is any good, it will also have customers who can eat in and take out.

IAM restaurant analogy

To draw an analogy with AWS IAM, the full time employees are like IAM users. They require long term access to the restaurant’s resources as shown above. These users will all belong to different groups – the waiters, chef, and cleaners group (that is, all waiters, for example, will have the same job title of “waiter”).

IAM restaurant analogy

How are the restaurant’s employees authenticated? How do we know that they are who they say they are? Name badges with a picture will do the job. This can also show their title which is analogous to the IAM group that they belong to.

The permission policies that define what resources the restaurant’s employees can access are applied on the group level, since every waiter, chef and cleaner will have the same permissions. This may not be true in reality, as the head chef for example may have privileged access. But for simplicity, let's assume it is true.

How does the restaurant manager control who has access to what resources? Doors with locks will do just fine. Keys act as a policy as they control access to parts of the restaurant.

An identical set will be given to all waiters, since waiters will need the same level of access to the food/drink storage room, kitchen, and seating area.

The same logic will apply to the other full time employees, where the appropriate set of keys are handed out so that they can use the restaurant’s resources as needed.

Giving keys to the restaurant employees is analogous to attaching a policy to an IAM user or group. Without the keys, the employees cannot access parts of the restaurant.

Similarly in AWS, without policies that explicitly allow an action, requests cannot be made to AWS resources. The default state in both AWS and our restaurant analogy is an implicit deny when trying to access resources.

The part time employees, like a temporary chef for example, and the customers, don’t need long term access to resources but will need short term access, analogous to IAM roles.

The part time employees can only work during a short window – say during evenings on the weekend. Outside of this time, they don’t have permissions to use the restaurant’s resources.

This part time chef does not have to be the same person. It could be a different person every week, unlike the full time employees that have specific identities.

A part time chef will therefore assume the role of a chef and get a temporary badge that they keep for the duration of their shift. This is analogous to an entity assuming an IAM role that has a policy attached to it and getting Temporary Security Credentials that will expire after some time.

Again, the policy here is the set of keys that grant permission to parts of the restaurant while the Temporary Security Credential is the temporary badge used to authenticate the chef.

Similarly, the customers are analogous to IAM roles for two reasons. First, they only require temporary access to the restaurant. Second, and perhaps more importantly, a successful restaurant will have tens of thousands to hundreds of thousands of unique customers over its lifetime.

Having a large number of unidentified entities is a perfect use case for IAM roles. Recall that with AWS, there is a hard limit of 5000 for the number of IAM users you can have. If there is a use case where the number of IAM users required will exceed this 5000 limit, using IAM roles is your only option around this.

Just like how IAM roles are assumed, the customer first needs to order something to prove that they are a customer and can assume the role of a customer.

After the customer role is assumed, the permissions policy attached to the customer role is then applied to the customer as well. Customers have permissions to only use some resources like the seating area and the toilet.

To keep the analogy realistic, access to the toilet is controlled by entering a passcode which changes every day, thus ensuring that the access is temporary. This passcode is analogous to the policy attached to the customer role that grants temporary access to the toilet.

Example Use Case of IAM Roles

Consider the following very simple architecture: an EC2 instance running an application that needs full access to an S3 bucket.

How would you give the EC2 instance the permission to read and write objects from an S3 bucket? This is explained in the diagram below:

Attaching a policy to an IAM role and letting an EC2 instance assume that role

1. Create an IAM role for your EC2 instance

2. Attach an IAM policy to the role that gives full access to the S3 bucket

3. Let the EC2 instance assume the role

The IAM policy for full S3 access mentioned in step #2 is:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:*",
                "s3-object-lambda:*"
            ],
            "Resource": "*"
        }
    ]
}

You can now read from and write to the S3 bucket. Notice that in the policy above, it doesn’t specify any ARN, but just says “*” for the resource. This means all S3 buckets. If that is what you want, then this policy is fine. But if you want to specify a single bucket, then you need to give the bucket ARN.

Wrapping Up

Understanding IAM and the difference between users, roles, groups and how policies work gives you a strong foundation on which you can architect and build secure solutions with AWS.

Thank you for reading!

In this article, you will learn:

• The differences between authentication and authorization
• How each of these processes work
• Examples of authorization and authentication in everyday life.

‌‌‌‌Ok, let's get started.

What is Authentication?

Authentication is the the process of verifying the credentials a user provides with those stored in a system to prove the user is who they say they are. If the credentials match, then you grant access. If not, you deny it.

Methods of Authentication

Single Factor authentication:

This is often used as the authentication process for lower risk systems. You only need a single factor to authenticate, with the most common being a password, so it's more vulnerable to phishing attacks and key loggers.

In addition to this, a recent article by DataProt showed that 78% of Gen-Z people utilize the same password for multiple services. This means that if an attacker gained access to one user account, they have a high probability of gaining access to others by simply using the same password.

2-Factor Authentication:

This method is more secure, as it comprises two factors of authentication – typically something you know, for example username and password , plus something you have / own, for example a phone SMS or a security token.

For 2-factor authentication, you would enter a one-time SMS password sent to your device, or perhaps a linked authenticator app code and provide an ever-changing access code.

As you can imagine, this is a lot more secure than simply entering a password, or a single authentication credential. You would need to know the login credentials, as well as have access to the physical device for the second part.

2-factor authentication has become very common amongst online services in recent years, and with many large companies it is the default authentication method. Many require that you setup 2-factor auth in order to even utilize the service.

Multi-Factor Authentication:

Going one step further to make your authentication process even more secure is having 3 or more factors. This form of authentication usually works on the premise of:

• something you know (username + password or a username + security question and answer)
• something you have (mobile phone sms, authenticator app, USB key)
• something you are (like a fingerprint / face recognition)

For these reasons, multi-factor authentication offers the most protection, as you would need to compromise multiple factors, and these factors are a lot more difficult to "hack" or replicate.

The downside to this method of authentication, and the reason it's not utilized in many average systems, is it can be cumbersome to setup and maintain. So the data / system you're protecting really has to justify the need for such security.

So, How Much Information Do You Need to Authenticate?

This question comes up at many security architecture meetings, and the answer is "it depends".

It is not unusual for companies to combine various authentication methods to increase security based on the nature of application.

For example, take a banking app. It contains very sensitive information, and could have a huge financial and reputational impacts should it be obtained by the wrong person. The bank may combine personal questions to be answered, along with a customer number and complex password.

On the other hand, for a social media site, you might only require a username and password, which is then checked and verified before allowing access.

It's all about the level of risk involved and what information someone can access once they're in the application. This helps determine the level of authentication you need.

If you or your team underestimates the level of authentication your app needs, you could be prosecuted for not securing the data within your system adequately. So companies employee security specialists to advise on best practices and appropriate solutions.

How Does Authentication Work in the Real World?

Let's take an example of a social media account. You choose your favorite social media site (which is hosted on a server). The server will ask you to provide credentials to access the site via a sign in page. Here you would type in your username and password that you used when creating the account.

Image showing the authentication process

These details are then sent to the server, and the authentication process begins. The details you provided are verified and checked in the server's database, and if they match the details on record you are authenticated. Then you're provided with a form of identification data, for example a cookie or Json Web Token (JWT token).

Success! You have accessed the site and are given entry.

You can learn more about JWT tokens in another FreeCodeCamp article by Beau Carnes here.

Next, let's look at authorization.

What is Authorization?

Authorization, is the process of verifying that you're allowed to access an area of an application or perform specific actions, based on certain criteria and conditions put in place by the application. You may also hear it called access control or privilege control.

Authorization can either grant or deny permission to carry out tasks, or access areas of an application.

Let's look at an example:

We've gained access to the social media site, but what we're allowed to do there depends on what we're authorized to to do.

If we try to access someone's profile that we're not friends with (they've not accepted our connection request), we're not authorized to view their profile. This means that we are denied permission to view their shared posts.

Image of authorization flow

How to Implement Authorization

There are many ways you can implement authorization depending on the frameworks you are using.

Within the .NET framework, for example, you could use role-based access control, or claims-based access control.

Role-based access control is centered around the ideology that each user within your system is assigned a role. These roles have predefined permissions associated with them. Being granted a role means that user will automatically inherit all these permissions. The roles are assigned at time of user creation and setup.

The endpoint or site simply then checks if the current logged-in user has the role of Admin when attempting to access the admin area.

The downside to this approach is that sometimes users are granted too many permissions that they don't need or shouldn't have.

For example, giving a user the role of Admin may mean they would have been givenAdvanced Create, Edit, Delete, and View user privileges. Whereas, you may want to only give them View and Basic Create permissions.

Claims-based access control can allow for finer tuning of a specific user's permissions. The application can either check that the claim simply exists on a user, or whether a particular value is assigned to the claim.

As an example, a claim called CreateUser could be given to a user, and this is checked when creating a user. Or you could assign a value of Advanced to the same claim, and then have different actions and user interface available depending whether the value was Advanced or Basic.

What's the Difference between Authentication and Authorization?

So now that we have a better understanding of the terms, let's look at a scenario you may be familiar with that involves both processes.

At a dinner party with an exclusive guest list, each guest is given a nickname and a secret password.

Upon arrival, a security guard asks you for your nickname and secret password. They then authenticate your credentials against the list they have. If your credentials match, you are handed an envelope showing you've been allowed in.

Once inside you are allowed to access the party and public areas of the venue as these require no authorization _(_everyone has the permission to enjoy the party). However, you then want to visit the VIP area.

As you approach, another security personnel asks to open your envelope (your permissions and roles). They take a look but unfortunately you do not have the VIP role, and therefore are not authorized to access.‌‌‌‌Put as simply as possible, authentication verifies the identity of a user or service allowing access, whereas authorization determines what they can do once they're in.

Why Should You Implement Both Authentication and Authorization?

As you can see, although authentication and authorization are very different, each plays an integral part in the security and integrity of the application or system.

These processes go hand in hand, and without one the other is kind of meaningless. If you can gain access to the Admin area, but do whatever you want once in there, it could lead to big problems.

On the other hand, you can't authorize individuals without knowing who they are! Which is why authentication always comes before authorization.

Closing Thoughts

I hope this has been insightful and you now have a clearer understanding of the differences between Authorization and Authentication, and how to use them.

Remember:

• Authenticate = Verifies the identity of a user or process.
• Authorize = Determines if the user / system has permission to use a resource or carry out an action.

Feel free to get in touch via Twitter if you wish to discuss this article in more detail @gweaths.

Prerequisites

You'll need the following to follow along with this tutorial:

• A working understanding of JavaScript.
• A good understanding of Node.js.
• A working knowledge of MongoDB or another database of your choice.
• Postman and a basic understanding of how it works.

Before we jump into the main part of the article, let's define some terms so we're all on the same page.

What is Authentication?

Authentication and authorization may seem like the same thing. But there's a big difference between getting into a house (authentication) and what you can do once you're there (authorization).

Authentication is the process of confirming a user's identity by obtaining credentials and using those credentials to validate their identity. If the certificates are valid, the authorization procedure begins.

You are probably already familiar with the authentication process, because we all go through it daily – whether at work (logging onto your computer) or at home (passwords or logging into a website). In fact, most "things" connected to the Internet require you to provide credentials to prove your identity.

What is Authorization?

Authorization is the process of granting authenticated users access to resources by verifying whether they have system access permissions or not. It also allows you to restrict access privileges by granting or denying specific licenses to authenticated users.

After the system authenticates your identity, authorization occurs, providing you full access to resources such as information, files, databases, finances, locations, and anything else.

This approval impacts your ability to access the system and the extent to which you can do so.

What is Cross-Origin Resource Sharing (CORS)?

CORS is an HTTP header-based system that allows a server to specify any other origins (domain, scheme, or port) from which a browser should enable resources to be loaded other than its own.

CORS also uses a system in which browsers send a "preflight" request to the server hosting the cross-origin help to ensure that it will allow the actual request.

We will be using the JSON web token standard to represent claims between two parties

What are JSON Web Tokens (JWT)?

JSON Web Tokens (JWT) are an open industry standard defined by RFC 7519 used to represent claims between two parties. jwt.io

You can use jwt.io to decode, verify, and create JWTs, for example.

JWT defines a concise and self-contained way of exchanging information between two parties as a JSON object. You can review and trust this information because it is signed.

JWTs can be signed with a secret (using the HMAC algorithm) or a public/private key pair from RSA or ECDSA. We'll see some examples of how to use them in a bit.

Let's get started.

How to Use a Token for Authentication in Node.js Development

To get started, first we'll need to set up our project.

Navigate to a directory of your choice on your machine and open it in the terminal to launch Visual Studio Code.

Then execute:

code.

Note: If you don't have Visual Studio Code installed on your computer, code . won't work. Just make sure you have it installed before trying this command.

How to Create a Directory and Set it Up with npm

Create a directory and initialize npm by typing the following command:

• In Windows power shell:

mkdir cors-auth-project

cd cors-auth-project

npm init -y

• In Linux:

mkdir cors-auth-project

cd cors-auth-project

npm init -y

How to Create Files and Directories

In the previous step, we initialized npm with the command npm init -y, which automatically created a package.json file.

We will create the model, middleware, and config directories and their files, for example, user.js, auth.js, database.js using the commands below.

mkdir model middleware config

touch config/database.js middleware/auth.js model/user.js

We can now create the index.js and app.js files in the root directory of our project with this command:

touch app.js index.js

This will give us a folder structure like the one you see below:

How to Install Dependencies

We'll install several dependencies like mongoose, jsonwebtoken, express, dotenv, bcryptjs, cors and development dependencies like nodemon to restart the server as we make changes automatically.

Because I'll be using MongoDB in this project, we'll install Mongoose, and the user credentials will be checked against what we have in our database. As a result, the entire authentication process isn't limited to the database we'll use in this tutorial.

npm install  cors mongoose express jsonwebtoken dotenv bcryptjs 

npm install nodemon -D

How to Create a Node.js Server and Connect your Database

Now, add the following snippets to your app.js, index.js, database.js, and .env files in that order to establish our Node.js server and connect our database.

In our database.js.:

config/database.js:

const mongoose = require("mongoose");

const { MONGO_URI } = process.env;

exports.connect = () => {
  // Connecting to the database
  mongoose
    .connect(MONGO_URI, {
      useNewUrlParser: true,
      useUnifiedTopology: true,
      useCreateIndex: true,
      useFindAndModify: false,
    })
    .then(() => {
      console.log("Successfully connected to database");
    })
    .catch((error) => {
      console.log("database connection failed. exiting now...");
      console.error(error);
      process.exit(1);
    });
};

In our app.js:

auth-cors-project/app.js

require("dotenv").config();
require("./config/database").connect();
const express = require("express");

const app = express();

app.use(express.json());

// Logic goes here

module.exports = app;

In our index.js:

auth-cors-project/index.js

const http = require("http");
const app = require("./app");
const server = http.createServer(app);

const { API_PORT } = process.env;
const port = process.env.PORT || API_PORT;

// server listening 
server.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

Our file, as you can see, requires various environment variables. If you haven't already, create a new .env file and add your variables before running the application.

In our .env.:

API_PORT=4001

MONGO_URI= // Your database URI

Edit the scripts object in our package.json to look like the one below to start our server.

"scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  }

We successfully inserted the above snippet into the files app.js, index.js, and database.js. So, we started by creating our Node.js server in index.js and then imported the app.js file, which already had routes configured.

Then, in database.js, we used Mongoose to build a database connection.

npm run dev is the command to start our application.

As long as they haven't crashed, both the server and the database should be up and running.

How to Create a User Model and Route

After registering for the first time, we'll establish our schema for the user details. Then, when logging in, we'll check them against the remembered credentials.

In the model folder, add the following snippet to user.js:

model/user.js

const mongoose = require("mongoose");

const userSchema = new mongoose.Schema({
  first_name: { type: String, default: null },
  last_name: { type: String, default: null },
  email: { type: String, unique: true },
  password: { type: String },
  token: { type: String },
});

module.exports = mongoose.model("user", userSchema);

Now let's create the routes for register and login, respectively.

In app.js in the root directory, add the following snippet for the registration and login.

app.js

// importing user context
const User = require("./model/user");

// Register
app.post("/register", (req, res) => {
// our register logic goes here...
});

// Login
app.post("/login", (req, res) => {
// our login logic goes here
});

How to Implement Register and Login Functionality

We'll implement these two routes in our application. Before storing the credentials in our database, we'll use JWT to sign them and bycrypt to encrypt them.

We will:

• Get user input from the /register route.
• Verify the user's input.
• Check to see if the user has already been created.
• Protect the user's password by encrypting it.
• Make a user account in our database.
• Finally, construct a JWT token that is signed.

Modify the /register route structure we created earlier to look as shown below:

app.js

// ...

app.post("/register", async (req, res) => {

  // Our register logic starts here
   try {
    // Get user input
    const { firstName, lastName, email, password } = req.body;

    // Validate user input
    if (!(email && password && firstName && lastName)) {
      res.status(400).send("All input is required");
    }

    // check if user already exist
    // Validate if user exist in our database
    const oldUser = await User.findOne({ email });

    if (oldUser) {
      return res.status(409).send("User Already Exist. Please Login");
    }

    //Encrypt user password
    encryptedUserPassword = await bcrypt.hash(password, 10);

    // Create user in our database
    const user = await User.create({
      first_name: firstName,
      last_name: lastName,
      email: email.toLowerCase(), // sanitize
      password: encryptedUserPassword,
    });

    // Create token
    const token = jwt.sign(
      { user_id: user._id, email },
      process.env.TOKEN_KEY,
      {
        expiresIn: "5h",
      }
    );
    // save user token
    user.token = token;

    // return new user
    res.status(201).json(user);
  } catch (err) {
    console.log(err);
  }
  // Our register logic ends here
});

// ...

Note: Update your .env file with a TOKEN_KEY, which can be a random string.

Using Postman to test the endpoint, we'll get the response shown below after successful registration.

We will:

• Get user input for the /login route.
• Verify the user's input.
• Check to see if the user is genuine.
• Compare the user's password to the one we saved earlier in our database.
• Finally, construct a JWT token that is signed.

Make the /login route structure that we defined earlier look like this:

// ...

app.post("/login", async (req, res) => {

  // Our login logic starts here
   try {
    // Get user input
    const { email, password } = req.body;

    // Validate user input
    if (!(email && password)) {
      res.status(400).send("All input is required");
    }
    // Validate if user exist in our database
    const user = await User.findOne({ email });

    if (user && (await bcrypt.compare(password, user.password))) {
      // Create token
      const token = jwt.sign(
        { user_id: user._id, email },
        process.env.TOKEN_KEY,
        {
          expiresIn: "5h",
        }
      );

      // save user token
      user.token = token;

      // user
      return res.status(200).json(user);
    }
    return res.status(400).send("Invalid Credentials");

  // Our login logic ends here
});

// ...

Using Postman to test, we'll get the response shown below after a successful login.

How to Create Middleware for Authentication

We can now create and login a user successfully. Now, we'll establish a route that requires a user token in the header, which will be the JWT token we created before.

Add the following snippet inside auth.js:

middleware/auth.js

const jwt = require("jsonwebtoken");

const config = process.env;

const verifyToken = (req, res, next) => {
  const token =
    req.body.token || req.query.token || req.headers["x-access-token"];

  if (!token) {
    return res.status(403).send("A token is required for authentication");
  }
  try {
    const decoded = jwt.verify(token, config.TOKEN_KEY);
    req.user = decoded;
  } catch (err) {
    return res.status(401).send("Invalid Token");
  }
  return next();
};

module.exports = verifyToken;

To test the middleware, create the /welcome route and edit app.js with the following code:

app.js

const auth = require("./middleware/auth");

app.post("/welcome", auth, (req, res) => {
  res.status(200).send("Welcome to FreeCodeCamp 🙌");
});

When we try to access the /welcome route we just built without sending a token in the header with the x-access-token key, we get the following response:

We can now re-test by adding a token in the header with the key x-access-token.

This is the response you'll get:

How to Implement Cross-Origin Resource Sharing (CORS)

CORS is a Node.js package that provides a Connect/Express middleware that you can. use to enable CORS with a variety of parameters.

1. It's easy to use (Enable All CORS Requests)

Adding the following snippet to app.js allows us to add CORS to our application and enable all CORS requests.

// ...

const cors = require("cors") //Newly added
const app = express();

app.use(cors()) // Newly added


app.use(express.json({ limit: "50mb" }));

// ...

2. You can enable CORS for a single route

Using the /welcome route as an example, you can activate CORS for a single route in your application by adding the following snippet in app.js.:

app.get('/welcome', cors(), auth, (req, res) => {
  res.status(200).send("Welcome to FreeCodeCamp 🙌 ");
});

3. How to configure CORS

We can set options in the CORS package by adding parameters to configure it, as shown below:

// ...

const corsOptions = {
  origin: 'http://example.com',
  optionsSuccessStatus: 200 // for some legacy browsers
}

app.get('/welcome', cors(corsOptions), auth, (req, res) => {
  res.status(200).send("Welcome to FreeCodeCamp 🙌 ");
});

// ...

You can check out NPM CORS PACKAGE to read more about Cross-Origin Resource Sharing.

You can click here to check out the complete code on GitHub.

Conclusion

In this article, we learned about JWT, authentication, authorization, and CORS. We also learned how to create an API in Node.js that uses a JWT token for authentication.

Thank you for reading!

In my 11 years as a developer, I have seen so many API's that have major security flaws. They either lack proper authentication or authorisation or both.

Developers might feel like everything's ok, since those endpoints are usually not public. But it is a huge security loop hole which anyone can easily target.

To better understand API security, let's create a demo project for the FBI. There will be an Admin who can enroll FBI Agents and change their clearance levels.

FBI Agents with Clearance Level 1 will be able to access public files, and agents with Clearance Level 2 will be able to access pubic and classified files.

But before we get started, here's some theory.

How Authentication Works

Our Agent has successfully cleared all their exams; time to enroll them. In order to do that they will provide their documents and in return will get their badge.

In the above scenario, providing documents is like logging in – where once verified, the agent will be provided with a token (badge). This process is called Authentication. It determines whether agents are who they claim to be.

We are going to use JSON Web Tokens (JWT) Bearer tokens for authentication. Bearer tokens are a type of token that's generated by servers, and which contain details of the claims/roles of a user trying to login. Bearer tokens are mostly structured tokens like JWT. You can read more about JWT here if you want to learn more.

How Authorisation Works

Now since the FBI Agent has gotten their badge, they can enter the FBI building. They are also able to access public files, but when trying to access classified files they get a 401 error.

This is because FBI Agent is not authorised to access classified files. Authorisation determines what agents can and cannot access.

As mentioned above, the JWT Bearer token contains claims/roles. Based on it, our server decides whether to give access to a private resource or not.

Access Flow

As you can see in the above diagram, on successful login the server returns a Bearer token. The client uses the bearer token in subsequent calls to access a private resource.

These are the two main concepts that we are going to implement in our article.

Enough with the theory, show me some code!

How to Set Up our Project

Create a new project by executing the command dotnet new webapi --name FBI from your CLI. It will create a project with a sample WeatherForecast API.

Why work on WeatherForecast when we can work on FBI? Go ahead and delete the WeatherForecast.cs file.

Add the necessary dependencies by executing these commands:

dotnet add package Microsoft.IdentityModel.Tokens --version 6.9.0
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer --version 5.0.4

In the ConfigureServices function in your Startup.cs file, add the below code:

var TokenValidationParameters = new TokenValidationParameters
{
    ValidIssuer = "https://fbi-demo.com",
    ValidAudience = "https://fbi-demo.com",
    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("SXkSqsKyNUyvGbnHs7ke2NCq8zQzNLW7mPmHbnZZ")),
    ClockSkew = TimeSpan.Zero // remove delay of token when expire
};

We are defining the parameters for validating a token. Make sure that the length of the string for generating SymmetricSecurityKey is 32.

Next, setup the services to add authentication for API's like this:

services
    .AddAuthentication(options =>
    {
        options.DefaultScheme = JwtBearerDefaults.AuthenticationScheme;
    })
    .AddJwtBearer(cfg =>
    {
        cfg.TokenValidationParameters = TokenValidationParameters;
    });

The AddAuthentication method registers services required by authentication services. It also configures the JWT Bearer Authentication as the default scheme.

The AddJwtBearer enables JWT-bearer authentication and setting the TokenValidationParameters defined above.

Now let's add some Authorisation claims for our Agent and Admin.

services.AddAuthorization(cfg =>
    {
        cfg.AddPolicy("Admin", policy => policy.RequireClaim("type", "Admin"));
        cfg.AddPolicy("Agent", policy => policy.RequireClaim("type", "Agent"));
        cfg.AddPolicy("ClearanceLevel1", policy => policy.RequireClaim("ClearanceLevel", "1", "2"));
        cfg.AddPolicy("ClearanceLevel2", policy => policy.RequireClaim("ClearanceLevel", "2"));
    });

The AddAuthorization method registers services required for authorisation. We are also adding claims for Admin, Agent, ClearanceLevel1 and ClearanceLevel2 by calling AddPolicy.

A claim is a name value pair that represents what the subject is. Since clearance level 2 can also access clearance level 1, we have put "1", "2" in ClearanceLevel1. You can read more about claims here.

Lastly, in the Configure method, add the below line just above app.UseAuthorization();:

app.UseAuthentication();

The Admin Controller File

Rename your file WeatherForecastController.cs to AdminController.cs. Do change the class name and constructor names as well. Finally, remove everything except the constructor.

using Microsoft.AspNetCore.Mvc;

namespace FBI.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class AdminController : ControllerBase
    {
        public AdminController() { }
    }
}

How to Set Up the Login API

Let's create a login API for Admin so that they can get a token to perform other tasks.

[HttpPost]
[Route("[action]")]
public IActionResult Login([FromBody] User User)
{
    // TODO: Authenticate Admin with Database
    // If not authenticate return 401 Unauthorized
    // Else continue with below flow

    var Claims = new List<Claim>
            {
                new Claim("type", "Admin"),
            };

    var Key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("SXkSqsKyNUyvGbnHs7ke2NCq8zQzNLW7mPmHbnZZ"));

    var Token = new JwtSecurityToken(
        "https://fbi-demo.com",
        "https://fbi-demo.com",
        Claims,
        expires: DateTime.Now.AddDays(30.0),
        signingCredentials: new SigningCredentials(Key, SecurityAlgorithms.HmacSha256)
    );

    return new OkObjectResult(new JwtSecurityTokenHandler().WriteToken(Token));
}

In the above code, User is a model with properties Username and Password. We are also creating an object of JwtSecurityToken using configurations that we have used in our Startup.cs file. The token is then converted to a string and returned in an OkObjectResult.

You can now open Swagger and execute the API to see a bearer token. A bearer token will be returned as you can see below.

Keep the token handy since we are going to use it in the next section. You can also visit https://jwt.io to analyse your token.

How to Generate the Badge API

Generating the badge for an Agent is a sensitive task and should only be authorised by an Admin. We are going to add an Authorize attribute for the GenerateBadge API.

[HttpPost]
[Route("[action]")]
[Authorize(Policy = "Admin")]
public IActionResult GenerateBadge([FromBody] Agent Agent)
{
    var Claims = new List<Claim>
    {
        new Claim("type", "Agent"),
        new Claim("ClearanceLevel", Agent.ClearanceLevel.ToString()),
    };

    var Key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("SXkSqsKyNUyvGbnHs7ke2NCq8zQzNLW7mPmHbnZZ"));

    var Token = new JwtSecurityToken(
        "https://fbi-demo.com",
        "https://fbi-demo.com",
        Claims,
        expires: DateTime.Now.AddDays(30.0),
        signingCredentials: new SigningCredentials(Key, SecurityAlgorithms.HmacSha256)
    );

    return new OkObjectResult(new JwtSecurityTokenHandler().WriteToken(Token));
}

Here, Agent is a model with properties Name as string and ClearanceLevel as int.

Now when you go back to swagger and try to execute the GenerateBadge API it will give you a 401 Unauthorised response. We are getting this error because we have not passed the bearer token.

To be able to add the Authorize header in Swagger, change the services.AddSwaggerGen as below:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "FBI", Version = "v1" });
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Please enter JWT with Bearer into field",
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement {
    { new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "Bearer"}
            },
        new string[] {}
    }
    });
});

When you refresh Swagger in your browser you will notice an Authorize button on the right side above the list of APIs.

Click on the newly added Authorize button in Swagger which will open up a dialog. We need to mention what type of token it is. So first enter Bearer in the field then a space and then the token generated from the /Admin/Login API from the previous section.

Click on the header to lock in the token. Now you are all set. When you execute the GenerateBadge API again you will get a token (analogous to badge). Keep this token handy, since we require it in the next section. Also make sure to pass ClearanceLevel as 1 for now.

How to Set Up the Agent Controller

Create a new file called AgentController.cs with the below content:

using Microsoft.AspNetCore.Mvc;

namespace FBI.Controllers
{
    [ApiController]
    [Route("[controller]")]
    [Authorize(Policy = "Agent")]
    public class AgentController : ControllerBase
    {
        public AgentController() { }
    }
}

As you can see above, we are authorising the whole controller for Agent's access only. So even Admin won't be able to access the API's we are going to create.

How to Access the Record's APIs

Let's add the APIs to access both public and classified files.

[HttpGet]
[Route("[action]")]
[Authorize(Policy = "ClearanceLevel1")]
public ActionResult<String> AccessPublicFiles()
{
    return new OkObjectResult("Public Files Accessed");
}

[HttpGet]
[Route("[action]")]
[Authorize(Policy = "ClearanceLevel2")]
public ActionResult<String> AccessClassifiedFiles()
{
    return new OkObjectResult("Classified Files Accessed");
}

We have added the Authorize attribute's for both API's such that public files can be accessed by ClearanceLevel1 and classified files can be accessed by ClearanceLevel2.

If you try to access these API's with the Admin token you will get 403 Forbidden error. So go ahead and click on the Authorize button again and click on logout. Then, get the token from the above step and paste in the field with Bearer as a prefix.

Now when you access the /Agent/AccessPublicFiles API you will see response 200 with the message Public Files Accessed. But when you try the classified API you get the 403 Forbidden error.

How to Change the Clearance Level

Fast forward 3 years and our Agent's performance has been mind bogglingly good. Management has now decided to promote them to ClearanceLevel2.

The Agent goes to the Admin and asks them to provide a token/badge with Clearance Level 2.

The Admin calls the /Admin/Login API to generate their own token first. They then enter it in the Authorize dialog.

The admin then calls the /Admin/GenerageBadge API with value 2 in the ClearanceLevel. This generates a new token/badge which they then hand over to Agent.

The Agent enters this token/badge in the Authorize dialog and when they now call /Agent/AccessClassifiedFiles they are pleased to see the result Classified Files Accessed.

Conclusion

You can find the whole project here on GitHub.

API security is extremely important and shouldn't be taken lightly, even if it's for internal use only. Setup Authentication and Authorisation and you are halfway there.

There are other other security measures you can take against DDoS attacks, accepting API's from a particular IP or domain only, and so on.

How did you like the article? What other security measures do you usually take? Any feedbacks or comments?

You can checkout out more tutorials on my site.

In the past month, I had a chance to implement JWT auth for a side project. I have previously worked with JWT in Ruby on Rails, but this was my first time in Spring.

In this post, I will try to explain what I have learned and applied in my project to share my experience and hopefully help some people.

We will start by taking a quick look at the theory behind JWT and how it works. Then we will look at how to implement it in a Spring Boot application.

JWT Basics

JWT, or JSON Web Tokens (RFC 7519), is a standard that is mostly used for securing REST APIs. Despite being a relatively new technology, it is gaining rapid popularity.

In the JWT auth process, the front end (client) firstly sends some credentials to authenticate itself (username and password in our case, since we're working on a web application).

The server (the Spring app in our case) then checks those credentials, and if they are valid, it generates a JWT and returns it.

After this step client has to provide this token in the request’s Authorization header in the “Bearer TOKEN” form. The back end will check the validity of this token and authorize or reject requests. The token may also store user roles and authorize the requests based on the given authorities.

Implementation

Now let’s see how we can implement the JWT login and save mechanism in a real Spring application.

Dependencies

You can see the list of Maven dependencies that our example code uses below. Note that the core dependencies like Spring Boot and Hibernate are not included in this screenshot.

Saving Users

We will start by creating controllers to save users securely and authenticate them based on username and password.

We have a model entity called User. It is a simple entity class that maps to the USER table. You can use whatever properties you need depending on your application.

We also have a simple UserRepository class to save users. We need to override the findByUsername method since we will use it in authentication.

public interface UserRepository extends JpaRepository<User, String>{ 
    User findByUsername(String username); 
}

We should never store plaintext passwords in the database because many users tend to use the same password for multiple sites.

There are many different hashing algorithms, but the most commonly used one is BCrypt and it is a recommended method of secure hashing. You can check out this article for more information on the topic.

To hash the password, we will define a BCrypt bean in @SpringBootApplication and annotate the main class as follows:

@Bean public BCryptPasswordEncoder bCryptPasswordEncoder() {
    return new BCryptPasswordEncoder(); 
}

We will call the methods on this bean when we need to hash a password.

We also need a UserController to save users. We create the controller, annotate it with @RestController, and define the corresponding mapping.

In our application, we save the user based on a DTO object that is passed from the front end. You can also pass a User object in @RequestBody.

After we pass the DTO object, we encrypt the password field using the BCrypt bean we created earlier. You could also do this in the controller, but it is a better practice to put this logic in the service class.

@Transactional(rollbackFor = Exception.class) 
public String saveDto(UserDto userDto) { 
    userDto.setPassword(bCryptPasswordEncoder
           .encode(userDto.getPassword())); 
    return save(new User(userDto)).getId(); 
}

Authentication Filter

We need authentication to make sure that the user is really who they claim to be. We will be using the classic username/password pair to accomplish this.

Here are the steps to implement authentication:

1. Create our Authentication Filter that extends UsernamePasswordAuthenticationFilter
2. Create a security configuration class that extends WebSecurityConfigurerAdapter and apply the filter

Here is the code for our Authentication Filter – as you might know, filters are the backbone of Spring Security.

Let’s go over this code step by step.

This class extends UsernamePasswordAuthenticationFilter which is the default class for password authentication in Spring Security. We extend it to define our custom authentication logic.

We make a call to the setFilterProcessesUrl method in our constructor. This method sets the default login URL to the provided parameter.

If you remove this line, Spring Security creates the “/login” endpoint by default. It defines the login endpoint for us, which is why we will not define a login endpoint in our controller explicitly.

After this line our login endpoint will be /api/services/controller/user/login. You can use this function to stay consistent with your endpoints.

We override the attemptAuthentication and successfulAuthentication methods of the UsernameAuthenticationFilter class.

The attemptAuthentication function runs when the user tries to log in to our application. It reads the credentials, creates a user POJO from them, and then checks the credentials to authenticate.

We pass the username, password, and an empty list. The empty list represents the authorities (roles), and we leave it as is since we do not have any roles in our application yet.

If the authentication is successful, the successfulAuthentication method runs. The parameters of this method are passed by Spring Security behind the scenes.

The attemptAuthentication method returns an Authentication object that contains the authorities we passed while attempting.

We want to return a token to user after authentication is successful, so we create the token using username, secret, and expiration date. We need to define the SECRET and EXPIRATION_DATE now.

We create a class to be a container for our constants. You can set the secret to whatever you want, but the best practice is making the secret key as long as your hash. We use the HS256 algorithm in this example, so our secret key is 256 bits/32 chars.

The expiration time is set to 15 minutes, because it is the best practice against secret key brute-forcing attacks. The time is in milliseconds.

We have prepared our Authentication filter, but it is not active yet. We also need an Authorization filter, and then we will apply them both through a configuration class.

This filter will check the existence and validity of the access token on the Authorization header. We will specify which endpoints will be subject to this filter in our configuration class.

Authorization Filter

The doFilterInternal method intercepts the requests then checks the Authorization header. If the header is not present or doesn’t start with “BEARER”, it proceeds to the filter chain.

If the header is present, the getAuthentication method is invoked. getAuthentication verifies the JWT, and if the token is valid, it returns an access token which Spring will use internally.

This new token is then saved to SecurityContext. You can also pass in Authorities to this token if you need for role-based authorization.

Our filters are ready, and now we need to put them into action with the help of a configuration class.

Configuration

We annotate this class with @EnableWebSecurity and extend WebSecurityConfigureAdapter to implement our custom security logic.

We autowire the BCrypt bean that we defined earlier. We also autowire the UserDetailsService to find the user’s account.

The most important method is the one which accepts an HttpSecurity object. Here we specify the secure endpoints and filters that we want to apply. We configure CORS, and then we permit all post requests to our sign up URL that we defined in the constants class.

You can add other ant matchers to filter based on URL patterns and roles, and you can check this StackOverflow question for examples regarding that. The other method configures the AuthenticationManager to use our encoder object as its password encoder while checking the credentials.

Testing

Let’s send a few requests to test if it works properly.

Here we send a GET request to access a protected resource. Our server responds with a 403 code. This is the expected behavior because we haven’t provided a token in the header. Now let’s create a user:

To create a user, we send a post request with our User DTO data. We will use this user to login and get an access token.

Great! We got the token. After this point, we will use this token to access protected resources.

We provide the token in the Authorization header and we are now allowed access to our protected endpoint.

Conclusion

In this tutorial I have walked you through the steps I took when implementing JWT authorization and password authentication in Spring. We also learned how to save a user securely.

Thank you for reading – I hope it was helpful to you. If you are interested in reading more content like this, feel free to subscribe to my blog at https://erinc.io. :)