@cubos/auth-module

@cubos/auth Module

About   |   Features   |   Usage   |   Endpoints   |   SignIn Explanation   |   Technologies   |  

:dart: About

Module to be used as authentication library

:sparkles: Features

• Password authentication
• SignIn (SCRAM) & (PLAIN)
• Create and maintain session

:grey_question: Usage

const realm = {
  name: "realm_name"
  authMethods: {
    type: "password",
    minLength: 3,
    maxLength: 15,
    checkPwned: true
  },
  session: {
    idleTimeout: 2592000,
    timeout: 2592000
  }
}

const configInstance = new ConfigClass([realm])
AuthModuleConfig.init(configInstance)

const authService = container.resolver(Auth)

:white_check_mark: Endpoints

• signUpWithPassword

• Validates the auth method configuration will be used in authentication process
• Validates the password
• Save user credentials
• Create user with corresponding entity configuration
• Return user

• signInWithPasswordPlain

  PLAIN As the name already says, a simple way to create session with less rules of cryptography

• Verify if user exist by realm and username
• Get the encrypt options that will be used to hash the password
• Generate hashed password
• Validates if password is compatible
• Create session

• signInWithPasswordScram

  SCRAM Salted Challenge Response Authentication Mechanism its a family of mechanisms to ensure password security, uses series of validations client-server to grant authentication

• Verify if user exist by realm and username
• Creates temporary sign in
  • If user don't exist return false credentials
• Get the auth credentials
• Return the credentials

• signInWithPasswordScramContinue

• Check if temporary sign in is valid
• Validates client proof
• Creates session
• Return server proof and token

• recoverSession

• Validates token
• Get session
• Validates session timeout
• Validates session idle timeout
• Return session

• updatePassword

• Fin user
• Validates the password
• Update password
• Return row affected

:green_check_mark: SignIn Explanation

• SCRAM

  • Cliente normaliza o username e a senha utilizando o algoritmo SASLprep (RFC 4013).
  • Cliente escolhe um ClientNonce aleatório composto por 32 bytes.
  • Cliente envia para o servidor UserName e ClientNonce, solicitando o início do processo de autenticação.
  • Servidor escolhe um ServerNonce aleatório composto por 32 bytes.
  • Servidor armazena no banco de dados um login em andamento com os dados UserName, ClientNonce e ServerNonce , com validade de 1 minuto.
  • Servidor responde com Salt, ServerNonce, ArgonMemory, ArgonIterations, ArgonParalelism, ArgonLength.
  • Cliente computa HashedPassword = Argon2id(Password, Salt) (custoso).
  • Cliente computa ClientKey = HMAC-SHA3-512(HashedPassword, "Client Key").
  • Cliente computa HashedClientKey = SHA3-512(ClientKey).
  • Cliente computa Auth = ClientNonce || ServerNonce || Salt.
  • Cliente computa ClientProof = ClientKey XOR HMAC-SHA3-512(HashedClientKey, Auth).
  • Cliente envia para o servidor UserName , ClientNonce, ServerNonce e ClientProof .
  • Servidor busca registro no banco de dados para confirmar que os primeiros 3 parâmetros corresponde a um processo de autenticação válido, iniciado a pouco tempo. Deleta esta linha do banco de dados (uso único).
  • Servidor computa Auth = ClientNonce || ServerNonce || Salt.
  • Servidor computa ClientKey = ClientProof XOR HMAC-SHA3-512(HashedClientKey, Auth).
  • Servidor verifica se SHA3-512(ClientKey) === HashedClientKey. Se essa igualdade for falsa, rejeitar autenticação.
  • Servidor computa ServerProof = HMAC-SHA3-512(ServerKey, Auth).
  • Servidor cria sessão para o usuário e produz um token bearer.
  • Servidor envia para o cliente o ServerProof, junto com o token de sessão
  • Cliente computa ServerKey = HMAC-SHA3-512(HashedPassword, "Server Key").
  • Cliente computa RefServerProof = HMAC-SHA3-512(ServerKey, Auth).
  • Cliente verifica se RefServerProof === ServerProof. Se essa igualdade for falsa, rejeitar autenticação.

• PLAIN

  • Cliente envia UserName e Password para o servidor.
  • Servidor normaliza o username e a senha utilizando o algoritmo SASLprep (RFC 4013).
  • Servidor computa HashedPassword = Argon2id(Password, Salt) (custoso).
  • Servidor computa ClientKey = HMAC-SHA3-512(HashedPassword, "Client Key").
  • Servidor computa HashedClientKey = SHA3-512(ClientKey).
  • Servidor verifica se HashedClientKey é o mesmo salvo em banco de dados. Se for, aceitar a autenticação e responder com token de sessão.

:rocket: Technologies

The following tools were used in this project:

• Node.js
• TypeScript
• Kysely

Back to top