Service Design Specification

Athentication documentation -Version:1.0.7

Scope

This document provides a structured architectural overview of the authentication module of the project.The authentication module of the project is used to generate authentication and authorization specific code for all services but a more specific purpose of the module is also to store all required configuration to generate an automatic user service for the project which is named 'ebaycclone-auth-service'.

So in this document you will find

• The detailed configuration of the authetication module.

• The effect of the authetication configuration on the auth (user) service and the detailed structures of the auto-generated user service.

• The effect of the authetication configuration on the resource services and the detailed authentication and authorization structures of a resource server.

This document has been automatically generated based on the authetication module definition within Mindbricks, ensuring that the information reflects the source of truth used during code generation and deployment.

The document is intended to serve multiple audiences:

• Service architects can use it to validate design decisions and ensure alignment with broader architectural goals.
• Developers and maintainers will find it useful for understanding the structure and behavior of the service, facilitating easier debugging, feature extension, and integration with other systems.
• Stakeholders and reviewers can use it to gain a clear understanding of the service's capabilities and domain logic.

Note for Frontend Developers: While this document is valuable for understanding business logic and data interactions, please refer to the Service API Documentation for endpoint-level specifications and integration details.

Note for Backend Developers: Since the code for this service is automatically generated by Mindbricks, you typically won't need to implement or modify it manually. However, this document is especially valuable when you're building other services—whether within Mindbricks or externally—that need to interact with or depend on this service. It provides a clear reference to the service's data contracts, business rules, and API structure, helping ensure compatibility and correct integration.

• API Test Interface (API Face): /
• Swagger Documentation: /swagger
• Postman Collection Download: /getPostmanCollection
• Health Checks: /health and /admin/health
• Current Session Info: /currentuser
• Favicon: /favicon.ico

This service is accessible via the following environment-specific URLs:

• Preview: https://ebaycclone.prw.mindbricks.com/auth-api
• Staging: https://ebaycclone-stage.mindbricks.co/auth-api
• Production: https://ebaycclone.mindbricks.co/auth-api

Authentication Essentials

Mindbricks provides a comprehensive authentication module that serves as the foundation for user management and security across all services. This module is designed to be flexible, allowing for the generation of authentication and authorization code tailored to project's specific needs. Mindbricks supports multiple authentication strategies, for the first validation of the user, the auth service supports the following authentication strategies:

• Password-based authentication: Users can log in using a username and password.
• Social login: Users can authenticate using third-party providers like Google, Facebook, or GitHub.
• Single Sign-On (SSO): Users can log in using an SSO provider, allowing for seamless access across multiple applications.
• API Key: Services can authenticate using API keys for secure communication. Once the user is validated through one of the above strategies, the user is granted a JWT token that can be used to access the protected resources of the service.

JWT tokens are generated by the auth service and can be used to access protected resources of the service. The JWT token is open and contains the user's identity and any additional claims required for authorization. The token is signed using a private RSA key, ensuring its integrity and authenticity. Once the JWT token is generated, it can be used to access protected resources of the service.

The JWT token is structured as follows:

{
  "keyId": "716a8738ec3d499f84d58bda6ee772ce",
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "sub": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  loginDate: "2023-10-01T12:00:00Z"
}

Key id for a token represents the private-public key pair used to sign the token. To validate the signature of the token, the public key is used. Any service which will use the JWT token can request a publick ket from the auth service using the following endpoint:

GET /publickey?keyId=[keyIdInToken]

Mindbricks generated services manages the key rotation automatically, so the public key is always up to date and valid for the JWT tokens generated by the auth service. If you add any manual service to the project which should validate the JWT token, you can use the public key endpoint to get the public key and validate the JWT token signature.

The JWT token life cycle is configured in the authentication module of the project. This project uses the following configuration for the JWT token: The token is valid for days after it is issued. And the private key used to sign the token is rotated every days.

Note that when a new key is generated to sign the JWT tokens, the old key is still valid for the period of days. So it is recommended to cache the old public keys for the period of days to validate the JWT tokens issued with the old keys.

The Login Definition

The login definition is a crucial part of the authentication module, as it defines how user and tenant model is defined. In this section it is specified how users, user groups, and tenants are defined in the project's data model. These definitions allow Mindbricks to dynamically extract identity and authorization data from project-specific data objects.

User Settings

Super Admin User Email: admin@admin.com** The login email of the super admin user. This user has full permissions across the project and is not tenant-scoped. If not defined, the project owner's email is used. This email must be unique and valid to support email-based features like verification and password reset.

Super admin user is created automatically when the project is initialized with a roleId of superAdmin and a userId of f7103b85-fcda-4dec-92c6-c336f71fd3a2.

Super Admin User Password: Super admin user password is defined in this module as well, but masked in this document. To edit it you can use the User Settings section of Login Definition chapter of the Mindbricks Authentication Module.

Username Type: The type of the username which is stored in the database and written to the session object for information purposes.: -asFullName: The username is stored in one property, fullname, and represents the full name of the user, which is a combination of first name and last name. -asNamePair: The username is stored in two properties, name and surname, which are combined to form the full name of the user.

This project uses the asFullName type, so the user name is stored in one property, fullname, and represents the full name of the user, which is a combination of first name and last name.

User Groups: The project does not support user groups, so the auth service will not create any user group related data objects.

Public User Registration: The project allows public user registration, meaning that users can register themselves without the need for an admin to create an account for them. This is useful for projects that require user self-registration, such as social networks, forums, or any application where users need to create their own accounts. The user registration process is handled by the auth service, which will create a new user data object in the database. The user registration process will create a new user with the userId and roleId set to user, and the user will be able to log in using the username and password they provided during registration. The reigstered user's roleId will be updated later to any other roleId by the super admin or admin users. If any social login is enabled for the project, the user can also sign up using the social login providers. Note that when users register themselves using socila logi, first all the data that can be provided by the social login provider will written to Redis cache with a key called socialCode, and this code will be returned to the api consumer, which can be used to complete the registration process.

Email Verification Required For Login: The project requires email verification for user login, meaning that users must verify their email address before they can log in. This is useful for projects that require email verification to ensure that users have provided a valid email address, such as social networks, forums, or any application where email verification is required. The email verification process is handled by the auth service, which will send a verification email to the user's email address after they register or change their email address. You can check the email verification details in the REST API documentation of the auth service.

Email 2FA Is Not Required For Login: The project does not require email-based two-factor authentication (2FA) for user login, meaning that users can log in using only their username and password without providing a second factor of authentication. This is useful for projects that do not require an additional layer of security for user login, such as enterprise applications, internal tools, or any application where email-based 2FA is not required. While the email 2FA is not required, the auth service will still support email 2FA if it is configured in the verification services. You can prefer email 2FA at any time before any action or make it optional which means that users can provide a second factor of authentication if they want to, but it is not required for login. You can check the email 2FA details in the REST API documentation of the auth service.

User Mobile Is Not Active: The authetication module is not configured to support mobile numbers for users.

User Auto Avatar Script: Mindbricks stores an avatar property inthe user data model automatically. This project supports also automatic avatar generation for users with the following script configuretion. The auth service will generate an avatar for each user when it is not specified in the registration process.

The script is defined in the authentication module and can be edited in the User Settings section of Login Definition chapter of the Mindbricks Authentication Module. The script is executed when a new user is created, and it generates an avatar based on user properties.

`https://gravatar.com/avatar/${LIB.common.md5(this.email ?? 'nullValue')}?s=200&d=identicon`

Tenant Settings

This project is not configured to support multi-tenancy, meaning that users and other data are not scoped to a specific tenant. This allows for a single-tenant data management, where all users and other data are shared across the project.

Verification Services

The project supports various verification services that enhance security and user experience. These services are designed to verify user identity through different channels, such as email and mobile, and can be configured to suit the project's needs. Please check the auth service API documentation for more details on how to use these services through the REST API.

A verification service is configured with the following settings: -verificationType: The type of verification handling, which can be one of the following: -- byCode: The verification is handled by entering a code in the frontend. -- byLink: The verification is handled by clicking a link in the frontend, which will automatically verify the user through the auth service. -resendTimeWindow: The time window in seconds during which the user can request a new verification code or link. -expireTimeWindow: The time window in seconds after which the verification code or link will expire and become invalid.

Password Reset By Email

The project supports password reset by email, allowing users to reset their passwords securely through a verification code sent to their registered email address. This service is useful for projects that require users to reset their passwords securely, such as social networks, forums, or any application where password reset is required. The password reset by email process is handled by the auth service, which will send a verification code to the user's email address after they request a password reset.

{
    verificationType: "byCode",
    resendTimeWindow: 60,
    expireTimeWindow: 86400
}

Password Reset By Mobile

The project supports password reset by mobile, allowing users to reset their passwords securely through a verification code sent to their registered mobile number. This service is useful for projects that require users to reset their passwords securely, such as social networks, forums, or any application where password reset is required. The password reset by mobile process is handled by the auth service, which will send a verification code to the user's mobile number after they request a password reset.

{
    verificationType: "byCode",
    resendTimeWindow: 60,
    expireTimeWindow: 300
}

Email Verification

The project supports email verification, allowing users to verify their email addresses securely through a verification code sent to their registered email address. This service is useful for projects that require users to verify their email addresses securely, such as social networks, forums, or any application where email verification is required. The email verification process is handled by the auth service, which will send a verification code to the user's email address after they register or change their email address.

{
    verificationType: "byCode",
    resendTimeWindow: 60,
    expireTimeWindow: 86400
}

Mobile Verification

The project supports mobile verification, allowing users to verify their mobile numbers securely through a verification code sent to their registered mobile number. This service is useful for projects that require users to verify their mobile numbers securely, such as social networks, forums, or any application where mobile verification is required. The mobile verification process is handled by the auth service, which will send a verification code to the user's mobile number after they register or change their mobile number.

{      
    verificationType: "byCode",
    resendTimeWindow: 60,
    expireTimeWindow: 300
}

Email 2FA

The project supports email-based two-factor authentication (2FA), allowing users to enhance their login security by providing a second factor of authentication, such as a verification code sent to their registered email address. This service is useful for projects that require an additional layer of security for user login, such as social networks, forums, or any application where email-based 2FA is required. The email 2FA process is handled by the auth service, which will send a verification code to the user's email address after they log in. The user must provide the verification code to complete the login process.

{
    verificationType: "byCode",
    resendTimeWindow: 60,      
    expireTimeWindow: 86400
}

Mobile 2FA

The project supports mobile-based two-factor authentication (2FA), allowing users to enhance their login security by providing a second factor of authentication, such as a verification code sent to their registered mobile number. This service is useful for projects that require an additional layer of security for user login, such as
social networks, forums, or any application where mobile-based 2FA is required. The mobile 2FA process is handled by the auth service, which will send a verification code to the user's mobile number after they log in. The user must provide the verification code to complete the login process.

{
    verificationType: "byCode",
    resendTimeWindow: 60,
    expireTimeWindow: 300
}       

Access Control (Not Configured)

The project does not support any access control mechanisms, meaning that users can access all resources without any restrictions. If you want to add access control mechanisms, you can do so in the Access Control chapter of Mindbricks Authentication Module.

Social Logins (Not Configured)

The project does not support any social logins, meaning that users cannot log in using their social media accounts. If you want to add social logins, you can do so in the Social Logins chapter of Mindbricks Authentication Module.

User Properties

phone address

The project supports above user properties, allowing for the storage of additional user information beyond the default properties. User properties are defined in the User Properties chapter of authentication module and can be edited in the User Properties section. These properties can be used to store additional information about users, such as preferences, settings, or any other custom data that is relevant to the project. User properties are stored in the user data object, and they can be accessed and modified through the auth service API.

To see a detailed configuretion of the user properties, please check the User Data Object docmentation below.

Auth Service Data Objects

The service uses a PostgreSQL database for data storage, with the database name set to ebaycclone-auth-service.

Data deletion is managed using a soft delete strategy. Instead of removing records from the database, they are flagged as inactive by setting the isActive field to false.

user Data Object

Object Overview

Description: A data object that stores the user information and handles login settings.

This object represents a core data structure within the service and acts as the blueprint for database interaction, API generation, and business logic enforcement. It is defined using the ObjectSettings pattern, which governs its behavior, access control, caching strategy, and integration points with other systems such as Stripe and Redis.

Core Configuration

• Soft Delete: Enabled — Determines whether records are marked inactive (isActive = false) instead of being physically deleted.
• Public Access: accessPrivate — If enabled, anonymous users may access this object’s data depending on API-level rules.

Redis Entity Caching

This data object is configured for Redis entity caching, which improves data retrieval performance by storing frequently accessed data in Redis. Each time a new instance is created, updated or deleted, the cache is updated accordingly. Any get requests by id will first check the cache before querying the database. If you want to use the cache by other select criteria, you can configure any data property as a Redis cluster.

Properties Schema

• Required properties are mandatory for creating objects and must be provided in the request body if no default value is set.

Default Values

Default values are automatically assigned to properties when a new object is created, if no value is provided in the request body. Since default values are applied on db level, they should be literal values, not expressions.If you want to use expressions, you can use transposed parameters in any business API to set default values dynamically.

• email: 'default'
• password: 'default'
• fullname: 'default'
• roleId: user

Always Create with Default Values

Some of the default values are set to be always used when creating a new object, even if the property value is provided in the request body. It ensures that the property is always initialized with a default value when the object is created.

• roleId: Will be created with value user

• emailVerified: Will be created with value false

Constant Properties

email

Constant properties are defined to be immutable after creation, meaning they cannot be updated or changed once set. They are typically used for properties that should remain constant throughout the object's lifecycle. A property is set to be constant if the Allow Update option is set to false.

Auto Update Properties

fullname avatar phone address

An update crud API created with the option Auto Params enabled will automatically update these properties with the provided values in the request body. If you want to update any property in your own business logic not by user input, you can set the Allow Auto Update option to false. These properties will be added to the update API's body parameters and can be updated by the user if any value is provided in the request body.

Hashed Properties

password

Hashed properties are stored in the database as a hash value, providing an additional layer of security for sensitive data.

Elastic Search Indexing

email fullname roleId emailVerified phone address

Properties that are indexed in Elastic Search will be searchable via the Elastic Search API. While all properties are stored in the elastic search index of the data object, only those marked for Elastic Search indexing will be available for search queries.

Database Indexing

email

Properties that are indexed in the database will be optimized for query performance, allowing for faster data retrieval. Make a property indexed in the database if you want to use it frequently in query filters or sorting.

Unique Properties

email

Unique properties are enforced to have distinct values across all instances of the data object, preventing duplicate entries. Note that a unique property is automatically indexed in the database so you will not need to set the Indexed in DB option.

Cache Select Properties

email

Cache select properties are used to collect data from Redis entity cache with a different key than the data object id. This allows you to cache data that is not directly related to the data object id, but a frequently used filter.

Secondary Key Properties

email

Secondary key properties are used to create an additional indexed identifiers for the data object, allowing for alternative access patterns. Different than normal indexed properties, secondary keys will act as primary keys and Mindbricks will provide automatic secondary key db utility functions to access the data object by the secondary key.

Filter Properties

email password fullname avatar roleId emailVerified phone address

Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API's that have "Auto Params" enabled.

• email: String has a filter named email

• password: String has a filter named password

• fullname: String has a filter named fullname

• avatar: String has a filter named avatar

• roleId: String has a filter named roleId

• emailVerified: Boolean has a filter named emailVerified

• phone: String has a filter named phone

• address: Object has a filter named adress