Root domain authentication for subdomains

To implement a system where the root domain handles authentication for subdomains, you can follow these general steps. This approach typically involves using a centralized authentication service, such as OAuth or JWT (JSON Web Tokens), to manage user sessions across different subdomains.

Step 1: Centralize Authentication on the Root Domain

1. Set Up an Authentication Server:

   • Use the root domain (e.g., example.com) to host your authentication server. This server will handle login, registration, and token issuance.

2. User Login and Token Issuance:

   • When a user logs in at the root domain, generate a JWT or a session token. This token should contain user information and permissions, and it should be signed to ensure its integrity.

3. Set a Cookie for the Root Domain:

   • Store the JWT in a cookie with the domain set to .example.com. This allows the cookie to be accessible by all subdomains (e.g., app1.example.com, app2.example.com).

   // Example of setting a cookie in JavaScript
   document.cookie = "authToken=your_jwt_token; domain=.example.com; path=/; secure; HttpOnly";
   

Step 2: Subdomain Authentication

1. Check for the Token:

   • On each subdomain, check for the presence of the authentication cookie. If the cookie is present, extract the JWT.

2. Validate the Token:

   • Validate the JWT by checking its signature and expiration. You can use libraries like jsonwebtoken in Node.js or jwt-decode in the browser to decode and verify the token.

   const jwt = require('jsonwebtoken');
   
   function verifyToken(token) {
       try {
           const decoded = jwt.verify(token, 'your_secret_key');
           return decoded;
       } catch (err) {
           console.error('Token verification failed:', err);
           return null;
       }
   }
   

3. Authorization:

   • Based on the decoded token, determine if the user has access to the specific subdomain. This can be done by checking the permissions or roles included in the token payload.

Step 3: Handling Token Refresh and Logout

1. Token Refresh:

   • Implement a mechanism to refresh tokens before they expire. This can be done by setting a short-lived access token and a longer-lived refresh token.

2. Logout:

   • To log out, clear the authentication cookie from the root domain. This will effectively log the user out from all subdomains.

   // Example of clearing a cookie
   document.cookie = "authToken=; domain=.example.com; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT";
   

Additional Considerations

• Security: Ensure that all communications are done over HTTPS to protect the token from being intercepted.
• Cross-Origin Resource Sharing (CORS): Configure CORS policies if your subdomains need to make API requests to the root domain.
• Single Sign-On (SSO): Consider implementing SSO if you have multiple applications that need to share authentication.

By following these steps, you can create a centralized authentication system that allows users to authenticate once at the root domain and access various subdomains seamlessly.