rauth

A simple SSO implementation in Rust

Table of contents

1. About
2. Endpoints
   1. Signup
   2. Reset
   3. Delete
   4. Totp
   5. Login
   6. Logout
3. Setup environment
4. Server configuration
5. Deployment
6. Debugging

About

The rauth project provides a SSO (Single Sign On) implementation that can be consumed as any of both, a Rust library or a gRPC service. Currently, the project includes all regular session-related actions as signup, login, logout, and so on. Plus TOTP(Time-based One Time Password) and email verification support.

Endpoints

Signup

Allows a new user to get registered into the system if, and only if, email and password are both valid.

Request

The signup transaction requires of two steps to get completed: the signup request, and the email verification. Both of them use the same endpoint to get performed, nonetheless, the signup request is the only one that must all fields. The email verification instead, shall provide the verification token in the corresponding header.

# Example of a gRPC message for the signup endpoint

{
    "email": "dummy@test.com" # an string containing the user's email,
    "pwd": "1234567890ABCDEF" # an string containing the user's password encoded in base64
}

Response

• If, and only if, the first step of the signup transaction completed successfully, Rauth will respond with the error E003 (require email verification).
• If, and only if, the email verification completed successfully, is sent an Empty response with the session token in the corresponding header.
• Otherwise, is provided one of the errors down below.

Error codes

| Code | Name | Description | | :------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | | E001 | ERR_UNKNOWN | Unprevisible errors | | E002 | ERR_NOT_FOUND | Token header not found | | E005 | ERR_INVALID_TOKEN | Token is invalid because of any of the following reasons: bad format, exp time exceeded, bad signature, nbf not satisfied, wrong knd or not catched. | | E006 | ERR_INVALID_FORMAT | Invalid format for email or password | | E007 | ERR_INVALID_HEADER | Token header must be encoded in base64 |

Reset

Allows an existing user to reset its password.

Request

The reset transaction requires of two steps to get completed: the email verification, and the password reset. Both of them use the same endpoint to get performed, nonetheless, they do differ in which fields are mandatory.

# Example of a gRPC message for the first step of the reset endpoint

{
    "email": "dummy@test.com" # an string containing the user's email,
    "pwd": "" # not required
    "totp": "" # not required
}

# Example of a gRPC message for the second step of the reset endpoint
{
    "email": "" # not required
    "pwd": "1234567890ABCDEF" # an string containing the user's password encoded in base64
    "totp": "123456" # the TOTP of the user, if enabled
}

The second step must provide in the corresponding header the token that the verification email gave to ensure the legitimacy of the action.

Response

• If, and only if, the first step of the reset transaction completed successfully, Rauth will respond with the error E003 (require email verification).
• If, and only if, the password reset completed successfully, is sent an Empty response with no errors.
• Otherwise, is provided one of the errors down below.

Error codes

| Code | Name | Description | | :------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | | E001 | ERR_UNKNOWN | Unprevisible errors | | E002 | ERR_NOT_FOUND | Token header not found | | E004 | ERR_UNAUTHORIZED | Totp required | | E005 | ERR_INVALID_TOKEN | Token is invalid because of any of the following reasons: bad format, exp time exceeded, bad signature, nbf not satisfied, wrong knd or not catched. | | E006 | ERR_INVALID_FORMAT | Password must be encoded in base64 | | E007 | ERR_INVALID_HEADER | Token header must be encoded in base64 | | E008 | ERR_WRONG_CREDENTIALS | The new password cannot match the old one or invalid user id. |

Delete

Allows an existing user to delete its account.

Request

The delete transaction requires the user to be logged in, so its session token must be provided in the corresponding header of the request.

# Example of a gRPC message for the delete endpoint

{
    "pwd": "1234567890ABCDEF" # an string containing the user's password encoded in base64
    "totp": "123456" # the TOTP of the user, if enabled
}

Response

• If, and only if, the deletion completed successfully, is sent an Empty response with no errors.
• Otherwise, is provided one of the errors down below.

Error codes

| Code | Name | Description | | :------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | | E001 | ERR_UNKNOWN | Unprevisible errors | | E002 | ERR_NOT_FOUND | Token header not found | | E004 | ERR_UNAUTHORIZED | Totp required | | E005 | ERR_INVALID_TOKEN | Token is invalid because of any of the following reasons: bad format, exp time exceeded, bad signature, nbf not satisfied, wrong knd or not catched. | | E007 | ERR_INVALID_HEADER | Token header must be encoded in base64 | | E008 | ERR_WRONG_CREDENTIALS | Password does not match or invalid user id. |

Totp

Allows an existing user to enable or disable the time-based one time password

Request

The totp transaction requires the user to be logged in, so its session token must be provided in the corresponding header of the request. Besides, the enabling option requires of two steps to get completed: the action itself, and the totp verification. In any case, the same endpoint is consumed.

# Example of a gRPC message for the totp endpoint

{
    "action": x, # where x may be 0 or 1 for enabling or disabling totp respectively
    "pwd": "1234567890ABCDEF" # an string containing the user's password encoded in base64
    "totp": "" # not required if, and only if, is the first step of enabling totp
}

# Example of a gRPC message for the second step of enabling the totp

{
    "action": 0, # 0: enable totp action
    "pwd": "1234567890ABCDEF" # an string containing the user's password encoded in base64
    "totp": "123456" # the correct totp for the given secret
}

Response

• If, and on