ita-sso

[kevinmamaqi]

Server-to-Server SSO Service: Design and Development Guide

Part 1: Design Specifications

1. Introduction

This document presents the architecture and design considerations for a server-to-server Single Sign-On (SSO) service. The service will be developed using Koa in a Node.js environment, integrated with TypeScript for type safety, and PostgreSQL for data persistence.

graph TD
    A[Client Service 1] -->|Authenticate| B[SSO Service]
    C[Client Service 2] -->|Authenticate| B
    B --> D{PostgreSQL Database}
    B -->|Provide Documentation| E[Swagger UI]

Loading

2. Functional Requirements

2.1. User Registration

Users will register sending API Key from the service, nif/cif (will be used as id), email and password.

2.2. User Authentication

Services authenticate using Service Identifier and Password/API key.
Upon successful authentication, they will receive:
Authentication Token (AuthToken)
Refresh Token (RefreshToken)

2.3. Token Validation

An endpoint will validate the authenticity of provided AuthTokens.
Mechanism to renew AuthToken using RefreshToken.

2.4. User Metadata

A JSON field user_meta for users to store specific metadata in a JSON column

2.5. OpenAPI Swagger Endpoint

A Swagger endpoint for API documentation and interactivity.

3. Technical Specifications

3.1. Backend Framework

Koa.js with TypeScript.

3.2. Data Persistence

classDiagram
    class user {
        +id: String (Primary Key)
        +email: String
        +password: String
        +user_meta: JSON
    }

Loading

PostgreSQL Database
Table Name: user
Fields: id, email, password, and user_meta.

3.3. Password/API Key Management

Passwords/API keys hashed using bcrypt or similar.

4. Endpoints

(Refer to previous content for the endpoints and their descriptions)

4.1. Registration (POST /users/register)

sequenceDiagram
participant Client as Client App
participant Server as SSO Server
Client->>Server: Send National ID + Email + Password
Server->>Server: Validate Email format and uniqueness
Server->>Server: Validate National ID format and uniqueness
Server->>Server: Hash Password
Server->>Database: Save National ID, Email, and Hashed Password
Database-->>Server: Confirmation of Saved Data
Server-->>Client: Registration Successful

Loading

Input: National ID, Email, Password
Output: Success/Failure message

4.2. Login (POST /users/login)

sequenceDiagram
participant Client as Client App
participant Server as SSO Server
Client->>Server: Send National ID + Password
Server->>Database: Retrieve Hashed Password for given National ID
Database-->>Server: Return Hashed Password
Server->>Server: Compare Hashed Password with sent Password
Server-->>Client: Generate AuthToken and RefreshToken (if successful)

Loading

Input: National ID, Password
Output: AuthToken, RefreshToken

4.3. Validate AuthToken (GET /tokens/validate)

sequenceDiagram
    Client Service->>SSO Service: Validate AuthToken
    SSO Service->>PostgreSQL Database: Check Token Validity
    PostgreSQL Database-->>SSO Service: Token Status
    SSO Service-->>Client Service: Token is Valid/Invalid

Loading

Input: AuthToken
Output: Valid/Invalid status

4.4. Renew AuthToken (POST /tokens/renew)

sequenceDiagram
    Client Service->>SSO Service: Request new AuthToken using RefreshToken
    SSO Service->>PostgreSQL Database: Validate RefreshToken
    PostgreSQL Database-->>SSO Service: Validation Response
    SSO Service-->>Client Service: New AuthToken (on success) OR Error (on failure)

Loading

Input: RefreshToken
Output: New AuthToken

4.5. Swagger Documentation (GET /swagger)

classDiagram
class Authentication {
  + register(nationalID: String, email: String, password: String): void
  + login(nationalID: String, password: String): Tokens
  + refreshToken(refreshToken: String): AuthToken
  + validateToken(authToken: String): Boolean
}

class Metadata {
  + setUserMeta(serviceID: String, data: JSON): void
  + getUserMeta(serviceID: String): JSON
}

class OpenAPI {
  + getSwaggerDefinition(): JSON
}

Authentication --|> Server : Exposes >
Metadata --|> Server : Exposes >
OpenAPI --|> Server : Exposes >

Loading

Interactive API documentation using OpenAPI and Swagger UI.

5. Security Considerations

Use HTTPS.
Ensure secure token generation and validation.
Hash passwords/API keys securely.
Implement strict access control.

---

Part 2: Implementation

1 Initial folder structure

sso-service/
│
├── src/
│   ├── controllers/
│   │   ├── authController.ts     # Handles authentication, token generation, and renewal
│   │   └── userController.ts  # Manages user registration and related operations
│   │
│   ├── models/
│   │   ├── db.ts                 # Sets up the PostgreSQL database connection
│   │   └── userModel.ts       # Defines the service model and related operations
│   │
│   ├── middleware/
│   │   ├── errorHandler.ts       # Centralized error handling middleware
│   │   ├── authMiddleware.ts     # Authenticates and validates tokens
│   │   └── logger.ts             # Logs incoming requests and other operations
│   │
│   ├── routes/
│   │   ├── authRoutes.ts         # Defines routes related to authentication
│   │   └── userRouter.ts      # Defines routes related to service registration and management
│   │
│   ├── utils/
│   │   ├── tokenUtil.ts          # Token generation, validation, and other utilities
│   │   └── passwordUtil.ts       # Password and API key hashing and validation utilities
│   │
│   ├── config/
│   │   └── index.ts              # Configuration settings (e.g., database credentials, JWT secrets)
│   │
│   └── app.ts                    # Sets up and initializes the Koa application
│
├── public/
│   └── swagger/                  # Swagger UI assets and OpenAPI definition
│
├── tests/
│   ├── auth.test.ts              # Unit tests for authentication functionality
│   └── user.test.ts           # Unit tests for service registration and management
│
├── .gitignore                    # Specifies intentionally untracked files to ignore
├── package.json                  # Lists package dependencies and scripts
├── tsconfig.json                 # TypeScript configuration file
└── README.md                     # Project overview and documentation

[danny-mv]

I have some questions:
Are the service information and API keys stored persistently?
Are tokens persisted within the system?
How are roles defined and managed within the system?
What is the process for password recovery in case a user forgets their password?
What information is stored in the metadata JSON?

[kevinmamaqi]

I have some questions:

Are the service information and API keys stored persistently?
Yes, but as environment variables could be enough to start.

Are tokens persisted within the system?
No

How are roles defined and managed within the system?
enum type roles, columne role in user table, expose patch method for user that allows to modify the roles.

What is the process for password recovery in case a user forgets their password?
Would come later

What information is stored in the metadata JSON?
Don't know yet, probably name, surname, avatarId, things as such. This will grow, it is an initial version to get login/registration mostly.

[alex0rpi]

I have 2 questions:
-I suppose each client Service has currently its own authentication system. Once the SSO service is implemented, in their respective backends they will have to wipe off all auth related routes, middlewares and controllers since all authentication, authorization and user management requests will be now headed towards the SSO right?
-All client services have their own database, right? If user data is now stored in a single separate database, the one managed by the SSO, how are data updates going to be implemented across databases where some records relate to their associated users. With an Event Bus? For example, if a user with a certain ROLE wants to be deleted from ITA, how is this event cascaded to other databases containing his/her related records?

[SergiFont]

I understand these concepts, correct me if I'm wrong on something please:

• Only one server-to-server SSO service for all the Client Services will exist.
• There will be a new database wich will store user's essential data only for register/authentication purposes.
• The databases from the Client Services will still store some (if not all) of the user's data for the respective purpose of each app. For example, the password will still be stored on each database, or it is enough if it is only stored on the SSO service database?