Identity Access Management API

The Identity Access Management API is a lightweight Identity and Access Management microservice designed to provide secure, stateless authentication and authorization for a distributed microservices architecture. This service acts as the central authentication provider for a project—handling user registration, login, logout, and token validation—and is the single source of truth for authenticating client requests. Both clients and other services interact with the IAM API to verify that incoming requests are properly authenticated.

For more details on JWT definition, construction, and usage, please see this JWT lesson.

Objectives

• User Registration:
  Allow new users to register by submitting a JSON payload containing a unique username, a valid email, and a secure password. The system enforces field length constraints and proper input formatting.
  Success: Returns a 201 status with a unique userId and confirmation message.
  Failure: Returns an error (400 or 409) if validation fails or if the email is already in use.

• User Login:
  Authenticate registered users by verifying their credentials. On success, the API issues a JWT that includes essential claims like userId, iat (issued at), and exp (expiration time).
  Success: Returns a 200 status with a JWT and the userId.
  Failure: Returns a 401 Unauthorized error for invalid credentials.

• User Logout:
  Invalidate the active JWT so that the user is effectively logged out. This can be implemented via token blacklisting or by relying on short-lived tokens.
  Success: Returns a 200 status with a confirmation message.
  Failure: Returns a 401 error if the token is invalid or expired.

• Token Validation:
  Provide an endpoint that allows other services to verify the authenticity and validity of a JWT.
  Success: Returns a 200 status with details of the token claims if the token is valid.
  Failure: Returns a 401 error if the token is invalid or expired.

Technical Specifications

Your api should run on the port 3033.

Endpoint Schemas

1. POST /auth/register

• Input:
  • Headers:
    Content-Type: application/json
  • Body:

    {
      "username": "string, required, max length 50",
      "email": "string, required, valid email format, max length 100",
      "password": "string, required, min length 8"
    }

• Output (Success):
  • Status: 201 Created
  • Body:

    {
      "userId": "string (UUID)",
      "message": "User registered successfully"
    }

• Output (Failure):
  • Status: 400 Bad Request or 409 Conflict
  • Body:

    {
      "error": "Descriptive error message"
    }

2. POST /auth/login

• Input:
  • Headers:
    Content-Type: application/json
  • Body:

    {
      "email": "string, required, valid email format",
      "password": "string, required"
    }

• Output (Success):
  • Status: 200 OK
  • Body:

    {
      "token": "string (JWT, must include userId, iat, and exp claims)",
      "userId": "string (UUID)"
    }

• Output (Failure):
  • Status: 401 Unauthorized
  • Body:

    {
      "error": "Invalid credentials"
    }

3. POST /auth/logout

• Input:
  • Headers:
    Authorization: Bearer <JWT token>
Content-Type: application/json
  • Body:

    {}

• Output (Success):
  • Status: 200 OK
  • Body:

    {
      "message": "User logged out successfully"
    }

• Output (Failure):
  • Status: 401 Unauthorized
  • Body:

    {
      "error": "Token is invalid or expired"
    }

4. POST /auth/validate

• Description:
  This endpoint allows other services to verify that a JWT is valid and extract its claims.
• Input:
  • Headers:
    Authorization: Bearer <JWT token>
Content-Type: application/json
  • Body:

    {}

• Output (Success):
  • Status: 200 OK
  • Body:

    {
      "valid": true,
      "claims": {
        "userId": "string (UUID)",
        "iat": "number",
        "exp": "number",
        "otherClaims": "..."
      }
    }

• Output (Failure):
  • Status: 401 Unauthorized
  • Body:

    {
      "error": "Token is invalid or expired"
    }

Authentication Logic

• JWT Creation and Signing:
  On a successful login, the IAM API generates a JWT by:

  1. Creating a header (e.g., { "alg": "HS256", "typ": "JWT" }) and Base64Url-encoding it.
  2. Creating a payload containing essential claims such as userId, iat, and exp, and Base64Url-encoding it.
  3. Signing the encoded header and payload with a secure secret key to produce a signature, which is also Base64Url-encoded.
  4. Combining the three parts into the final JWT: <encoded header>.<encoded payload>.<encoded signature>.

• JWT Validation:
  Protected endpoints, as well as the dedicated /auth/validate endpoint, require the client to include the JWT in the Authorization header. The API validates the token by:

  • Verifying that the token has three parts separated by periods.
  • Decoding the header and payload to ensure they are valid Base64Url-encoded JSON.
  • Verifying the token’s signature with the secret key.
  • Checking the exp claim to ensure the token has not expired.

• Token Invalidation:
  Logout functionality may be implemented by token blacklisting or relying on short token lifetimes. Any subsequent request with an invalidated token is rejected with a 401 Unauthorized status.

Client and Service Interaction

This IAM API is designed to be used as the central authentication provider:

• Clients authenticate by calling the /auth/login endpoint and receive a JWT. They include this JWT in the Authorization header (using the Bearer schema) in all requests to protected endpoints.
• Other Services verify client authentication by calling the /auth/validate endpoint or by performing local JWT validation (if they share the secret key). This ensures that only authenticated requests are processed.

Example Header for Client Requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Your api should run on the port 3033.

Conclusion

The IAM API is a foundational microservice that provides robust, stateless authentication and authorization using JWTs. By defining clear endpoint schemas and authentication logic—including a dedicated token validation endpoint—this service serves as the central authentication provider for any project. It ensures that both client requests and inter-service communications are securely authenticated, supporting the scalability and security needs of modern distributed systems.