OAuth JWT Integration

Welcome back! In the previous lesson, you learned how to use mock OAuth providers to simulate real-world authentication flows, and you explored how to link and unlink accounts securely. You also saw how important it is to have strong security practices, such as requiring confirmation before linking accounts and preventing duplicate links. These features help keep user accounts safe and flexible.

Now, let's take the next step in building a robust authentication system. In modern web applications, JWTs (JSON Web Tokens) are a popular way to securely manage user authentication and authorization. JWTs allow your server to issue a signed token to the client after a successful login, which the client can then use to access protected resources. This approach is especially important in OAuth systems, where users might sign in using different providers, such as Google or GitHub.

In this lesson, you will learn how to integrate JWT tokens into your OAuth system to manage authentication in a unified and secure way. By the end, you will understand how to generate JWTs for different authentication methods, verify them in middleware, and enforce permissions based on the user's authentication context. This will prepare you for hands-on practice and more advanced OAuth integrations.

Let's start by looking at how JWT tokens are created in a unified authentication system. The generateUnifiedToken function is responsible for generating a JWT that contains all the information needed to identify the user and their authentication method.

Here is the function:

import jwt from 'jsonwebtoken';
import { randomBytes } from 'crypto';

export const generateUnifiedToken = (user: User, authMethod: string): string => {
  const payload: Partial<UnifiedJWTPayload> = {
    userId: user.id,
    authMethod,
    provider: user.provider
  };
  
  // Add cryptographically secure unique token ID for enhanced security
  if (authMethod !== 'password') {
    payload.jti = randomBytes(16).toString('hex');
  }
  
  const expiry = authMethod === 'password' 
    ? AUTH_CONFIG.tokenExpiry.password 
    : AUTH_CONFIG.tokenExpiry.oauth;
  
  return jwt.sign(payload, JWT_SECRET_KEY, { expiresIn: expiry });
};

At the top of the file, we import the jsonwebtoken library, which provides the tools we need to create and verify JWTs. The jwt.sign() method takes three arguments: the payload (the data you want to encode), a secret key (used to sign the token so it can be verified later), and options like the expiration time. This method returns a signed token string that can be sent to the client. The JWT_SECRET_KEY is a secret string stored securely on your server — it should never be exposed to clients. When you call jwt.sign(), it creates a cryptographically signed token that proves the payload hasn't been tampered with.

When you call this function, it creates a payload that includes the user's ID, the authentication method (such as password, google, or github), and the provider. If the authentication method is not password, it also adds a cryptographically secure unique token ID (jti) for extra security. The token's expiry time is set based on the authentication method — password tokens might last for one day, while OAuth tokens could last for a week.

For example, if a user logs in with a password, the payload might look like this:

{
  "userId": 42,
  "authMethod": "password",
  "provider": "local"
}

But if a user logs in with Google OAuth, the payload could look like this:

{
  "userId": 99,
  "authMethod": "google",
  "provider": "google",
  "jti": "a1b2c3d4e5f6789012345678901234ab"
}

This approach makes it easy to handle different authentication methods in a consistent way, while also allowing you to set different security rules for each method. The use of cryptographically secure random bytes for the jti field ensures that each token has a unique identifier that cannot be predicted or reproduced by malicious actors.

Once a JWT token is generated and sent to the client, you need a way to verify it on every request to protected endpoints. This is where the unifiedAuth middleware comes in. Its job is to check the Authorization header for a valid JWT, decode it, and load the user's information.

Here's how the middleware works:

export const unifiedAuth = async (req, res, next) => {
  const authHeader = req.headers.authorization;
  
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing or invalid authorization header' });
  }
  
  const token = authHeader.split(' ')[1];
  
  try {
    const decoded = jwt.verify(token, JWT_SECRET_KEY) as UnifiedJWTPayload;
    const user = await User.findByPk(decoded.userId);
    
    if (!user) {
      return res.status(404).json({ error: 'User not found' });
    }
    
    // Create authentication context
    const authContext: AuthContext = {
      user,
      authMethod: decoded.authMethod as any,
      isOAuth: decoded.authMethod !== 'password',
      permissions: determinePermissions(user, decoded.authMethod),
      tokenInfo: {
        issued: new Date(decoded.iat * 1000),
        expires: new Date(decoded.exp * 1000),
        jti: decoded.jti
      }
    };
    
    // Attach context to request
    req.authContext = authContext;
    req.user = user;
    
    next();
  } catch (error) {
    if (error.name === 'TokenExpiredError') {
      return res.status(401).json({ error: 'Token expired' });
    }
    return res.status(401).json({ error: 'Invalid token' });
  }
};

When a request comes in, the middleware checks for a Bearer token in the header. If the token is missing or invalid, it returns an error. If the token is valid, it decodes the payload and fetches the user from the database. It then creates an authContext object, which includes the user, the authentication method, whether the user logged in with OAuth, their permissions, and token details like when it was issued and when it expires.

This authContext is attached to the request, so any route handler or middleware that runs later can access it. This makes it easy to enforce permissions and customize behavior based on how the user authenticated.

Not all users should have the same permissions. For example, an admin might be able to delete any resource, while a regular user can only delete their own. The determinePermissions function decides what permissions a user has based on their role and authentication method.

Here's how it works:

const determinePermissions = (user: User, authMethod: string): string[] => {
  const basePermissions = ['read', 'write'];
  
  // OAuth users get additional permissions
  if (authMethod !== 'password') {
    basePermissions.push('oauth_linked');
  }
  
  // Admin users get all permissions
  if (user.role === 'ADMIN') {
    basePermissions.push('admin', 'delete_any');
  } else {
    basePermissions.push('delete_own');
  }
  
  return basePermissions;
};

If a user logs in with OAuth, they get an extra permission called oauth_linked. If the user is an admin, they get admin and delete_any permissions. Regular users get delete_own.

To enforce these permissions, the requirePermission middleware checks if the current user has the required permission before allowing access to a route. For example, if a route requires admin permission, only users with that permission can proceed.

Here's a simple example:

export const requirePermission = (permission: string) => {
  return (req, res, next) => {
    const authContext = req.authContext as AuthContext;
    
    if (!authContext) {
      return res.status(401).json({ error: 'Authentication required' });
    }
    
    if (!authContext.permissions.includes(permission)) {
      return res.status(403).json({ 
        error: `Insufficient permissions. Required: ${permission}`,
        authMethod: authContext.authMethod,
        availablePermissions: authContext.permissions
      });
    }
    
    next();
  };
};

If a user tries to access a protected route without the right permission, they will see a response like this:

{
  "error": "Insufficient permissions. Required: admin",
  "authMethod": "password",
  "availablePermissions": ["read", "write", "delete_own"]
}

This system makes it easy to control access based on both the user's role and how they authenticated.

Now that you have a way to generate and verify JWTs, you can use them to build useful endpoints for your application. The /status endpoint lets clients check the current authentication status, providing detailed information about the user, their permissions, and capabilities.

Here's how the /status endpoint works:

import { User } from '../models/User';

router.get('/status', requirePermission('read'), (req, res) => {
  const authContext = req.authContext!;
  const user = authContext.user;
  
  res.json({
    user: {
      id: user.id,
      username: user.username,
      email: user.email,
      provider: user.provider,
      profileImage: user.profileImage
    },
    authentication: {
      method: authContext.authMethod,
      isOAuth: authContext.isOAuth,
      permissions: authContext.permissions,
      tokenInfo: authContext.tokenInfo
    },
    capabilities: {
      canLinkAccounts: !authContext.isOAuth,
      canCreateApiKeys: true,
      canAccessAdmin: authContext.permissions.includes('admin')
    },
    linkedAccounts: {
      google: !!user.googleId,
      github: !!user.githubId,
      local: !!user.password
    }
  });
});

When a client calls this endpoint with a valid token, they get a response showing their user info, authentication method, permissions, and what actions they can perform. Note the use of the non-null assertion operator (!) when accessing req.authContext — this tells TypeScript that we know the value exists because the requirePermission middleware guarantees it. For example:

{
  "user": {
    "id": 42,
    "username": "alice",
    "email": "alice@example.com",
    "provider": "local",
    "profileImage": null
  },
  "authentication": {
    "method": "password",
    "isOAuth": false,
    "permissions": ["read", "write", "delete_own"],
    "tokenInfo": {
      "issued": "2024-06-01T12:00:00.000Z",
      "expires": "2024-06-02T12:00:00.000Z"
    }
  },
  "capabilities": {
    "canLinkAccounts": true,
    "canCreateApiKeys": true,
    "canAccessAdmin": false
  },
  "linkedAccounts": {
    "google": false,
    "github": false,
    "local": true
  }
}

This endpoint is particularly useful for client applications that need to display user information, show or hide features based on permissions, or determine when a token is about to expire.

The /refresh endpoint allows clients to get a new token before the old one expires. This is useful for keeping users logged in without making them sign in again. Here's how it works:

router.post('/refresh', requirePermission('read'), (req, res) => {
  const authContext = req.authContext!;
  const user = authContext.user;
  
  try {
    // Generate new token with same authentication method
    const newToken = generateUnifiedToken(user, authContext.authMethod);
    
    res.json({
      message: 'Token refreshed successfully',
      token: newToken,
      authMethod: authContext.authMethod,
      expiresIn: authContext.isOAuth ? AUTH_CONFIG.tokenExpiry.oauth : AUTH_CONFIG.tokenExpiry.password
    });
  } catch (error) {
    console.error('Token refresh error:', error);
    res.status(500).json({ error: 'Failed to refresh token' });
  }
});

The endpoint uses the requirePermission('read') middleware to verify the current token and ensure the user has at least read permissions. It then calls generateUnifiedToken to create a new token with the same authentication method. The expiry time is determined by checking if the user authenticated via OAuth or password. The try-catch block handles any errors that might occur during token generation, ensuring the client receives a clear error message if something goes wrong.

For example, after calling /refresh, the response might be:

{
  "message": "Token refreshed successfully",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authMethod": "password",
  "expiresIn": "1d"
}

This endpoint is very useful in real-world applications where clients need to keep their sessions active. By refreshing tokens before they expire, you can provide a seamless user experience without forcing users to log in repeatedly.

In this lesson, you learned how to integrate JWT tokens into your OAuth authentication system. You saw how to generate unified tokens for different authentication methods, verify them using middleware, and attach an authentication context to each request. You also explored how to determine and enforce permissions, and how to use JWTs with endpoints that report authentication status and refresh tokens.

These concepts are essential for building secure and flexible authentication systems in modern web applications. You are now ready to put these ideas into practice in the CodeSignal IDE. In the next exercises, you will work directly with the code to generate tokens, protect routes, and manage permissions. Great job making it this far — these skills will serve you well as you continue to build advanced OAuth integrations!