Skip to content

sellersindustry/authical-backend

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits

app

app

 
 

src

src

 
 

.eslintrc.js

.eslintrc.js

 
 

.gitignore

.gitignore

 
 

LICENSE

LICENSE

 
 

README.md

README.md

 
 

authical.config.ts

authical.config.ts

 
 

banner.png

banner.png

 
 

next.config.js

next.config.js

 
 

package-lock.json

package-lock.json

 
 

package.json

package.json

 
 

tsconfig.json

tsconfig.json

 
 

Repository files navigation

alt text

Authical - Backend Server

This is the Backend Server for the Authical Authentication Framework, which acts as the backend service. Built using NextJS this server is the handles all the API calls made from the frontend to manage authenication, sessions, and account information. It is this service that connects to your databases like Redis and MongoDB to store user information.

You might also want to check out...


What is Authical?

Authical is an open source authentication framework that uses one-time passwords to authenicate users. A user can simply enter their email (no matter if they are a new user or an existing user) and they will receive an email within seconds with a one-time password (OTP) they can enter to confirm their identity. Authical is a easy to deploy framework that will manage one-time passwords, sessions, and user accounts.


Endpoint Authenication

There are two primary entities that will interact with the Authical authenication server. The first and most common type of entity is the client, this is the end user who is most likly interacting with the Authical server from their web browser. The second type of entity is a machine, this would be a service implemented by the developers that are using Authical as their autheication service. Machines are able to execute all admin API methods (except the methods related to machine tokens).

Client Authenication

Client bearers are generated and returned by the server when user finish the authorize process. Send this bearer as a bearer authorization header when making requests.

btoa(`USER:${userID}:${sessionID}:${secret}`);

Machine Authenication

Machine bearers are generated in the admin control panel or using the token add API endpoint. Send this bearer as a bearer authorization header when making requests.

btoa(`MACHINE:${tokenID}:${secret}`)

Configuration

Docs Coming Soon...


Setup

Docs Coming Soon...


Future Ideas

  • Authical Badge - Add Link to authical badge
  • MongoDB Integration - Implement MongoDB Integrations for profile.
  • Azure Mail Integration - Implement Azure email integration.
  • Query Users Admin - Ability to query and list active users within the admin user management
  • Session Location - Using the IP address get the location of the user. This location will have to be loaded from a interface API, so create a new interface also we should cache the varibles. IP Location API. There is a chance Vercel will handle this for us and in this case is should already be handled.
  • Post Hog Integration - Implement PostHog for logging.
  • Admin Panel Settings - Add a more user-friendly way to update the settings.
  • React Package - Create React package for UI assets.
  • Branding - Load custom branding from server settings.
  • Multiple Request - Prevent client from making multiple request at the same time that are duplicated.
  • Host URLs Trailing Forward Slash - the SDKs and authical.config.ts host names must have no trailing backslash in their urls. Make it so it does not matter. Make a core utility to handle this.
  • Email OTP Copy - In Outlook when notifications popup from emails it has a copy option to copy the otp.

APIs Endpoints

URL Method Description Docs
/auth/request POST Request new session Learn More
/auth/verify POST Verify new session Learn More
/session/ GET Get current session Learn More
/session/ DELETE Revolk current session Learn More
/session/ POST Refresh current session Learn More
/session/all GET Get all sessions Learn More
/session/all DELETE Revolk all sessions Learn More
/session/[id] GET Get session by ID Learn More
/session/[id] DELETE Revolk session by ID Learn More
/profile/ GET Get Profile Learn More
/profile/ POST Update Profile Learn More
/profile/ DELETE Delete Profile Learn More
/profile/[email] POST Add Email to Profile Learn More
/profile/[email] DELETE Remove Email from Profile Learn More
/profile/[email]/primary POST Set Primary Email for Profile Learn More
/profile/[email]/verify POST Verify Email for Profile Learn More
/user/[id/email] GET Get Profile by userID or email Learn More
/admin/settings GET Get Settings Learn More
/admin/settings POST Update Settings Learn More
/admin/log GET Get Logs Learn More
/admin/user/[id/email] GET Admin Get Profile by userID or email Learn More
/admin/user/[id/email] POST Admin Update Profile by userID or email Learn More
/admin/user/[id/email] DELETE Admin Delete by userID or email Learn More
/admin/token GET Get all API Tokens Learn More
/admin/token POST Create new API Token Learn More
/admin/token/[tokenID] GET Get token by Token ID Learn More
/admin/token/[tokenID] DELETE Delete token by Token ID Learn More
/admin/session/verify POST Verify user session by bearer token Learn More

Request New Session

POST:/auth/request No Auth Required
Requesting a new session will send a one time password to your email address. Once you receive the password you can verify the login with the Verify New Session API. No account is required, will auto create an account if one doesn't already exist. Will revolk current session on your device.

// Example Request
{
    "email": "bob@example.com"
}

// Example Response
{
    "otpID": "371c26bf-6f04-421b-b659-677159842e7e"
}

Verify New Session

POST:/auth/verify No Auth Required
Verifying a new session with the OTP ID and the One Time Password sent to your email address. Request a OTP with the Request New Session API. Will revolk current session on your device. The bear token that is returned should saved and henceforth be sent as an Authorization header such that Bearer [token]. See User Authenication.

// Example Request
{
    "email": "bob@example.com",
    "otpID": "371c26bf-6f04-421b-b659-677159842e7e",
    "secret": "7528"
}

// Example Response
{
    "bearer": "ZGYwZDE2NWUtZjYzOS00OGM0LTkwY2ItM2="
}

Get Current Session

GET:/session Client Basic Auth Required
Get the session information for the current session. Based on Authorization header.

// Example Response
{
    "id": "b81d9a79-936a-4f95-b402-530321952393",
    "user": "df0d165e-f639-48c4-90cb-3ba82450c613",
    "device": {
        "os": "",
        "browser": "",
        "ip": "",
        "location": "?"
    },
    "updated": "2023-10-13T01:22:33.352Z",
    "created": "2023-10-13T01:22:33.352Z"
}

Revolk Current Session

DELETE:/session Client Basic Auth Required
Revolk the session information for the current session. Based on Authorization header.

Refresh Current Session

POST:/session Client Basic Auth Required
Refresh the session information for the current session. This will increase the lifespan of the token. By default session last 24 days. No new bearer token is provided. Based on Authorization header.

Get All Sessions

GET:/session/all Client Basic Auth Required
Get all the current active session for the current user.

// Example Response
[
    {
        "id": "b81d9a79-936a-4f95-b402-530321952393",
        "user": "df0d165e-f639-48c4-90cb-3ba82450c613",
        "device": {
            "os": "",
            "browser": "",
            "ip": "",
            "location": "?"
        },
        "updated": "2023-10-13T01:22:33.352Z",
        "created": "2023-10-13T01:22:33.352Z"
    }
]

Revolk All Sessions

DELETE:/session/all Client Basic Auth Required
Revolk all the current active session for the current user - including current session, will log user out.

Get Session by ID

GET:/session/[id] Client Basic Auth Required
Get the session for a specific sessionID of the current user.

// Example Request URL
// /session/b81d9a79-936a-4f95-b402-530321952393

// Example Response
{
    "id": "b81d9a79-936a-4f95-b402-530321952393",
    "user": "df0d165e-f639-48c4-90cb-3ba82450c613",
    "device": {
        "os": "",
        "browser": "",
        "ip": "",
        "location": "?"
    },
    "updated": "2023-10-13T01:22:33.352Z",
    "created": "2023-10-13T01:22:33.352Z"
}

Revolk Session by ID

DELETE:/session/[id] Client Basic Auth Required
Revolk the session for a specific sessionID of the current user. If this is the current session will log the user out.

// Example Request URL
// /session/b81d9a79-936a-4f95-b402-530321952393

Get Profile

GET:/profile/ Client Basic Auth Required
Get user's profile information for the current session. The avatar is in base64 image format with the format data:image/png;base64, prepending it. The pending emails are emails that have yet to be verified. While the previous emails are the emails that have been removed and are no longer connected to your account.

// Example Response
{
    "id": "f09496bc-ed7f-4e11-8f33-f610c5bbcabc",
    "avatar": "data:image/png;base64,iVBORw0KGgoAAA....",
    "name": {
        "first": "",
        "last": ""
    },
    "email": {
        "primary": "bob@example.com",
        "active": [
            "bob@example.com"
        ],
        "pending": [{
            "email": "bob2@example.com",
            "update": "2023-10-13T01:22:33.352Z"
        }],
        "previous": [{
            "email": "notbob@example.com",
            "update": "2023-10-13T01:22:33.352Z"
        }]
    },
    "metadata": {},
    "isAdmin": false
}

Update Profile

POST:/profile/ Client Basic Auth Required
Update user's profile information for the current session. You are unable to update any email details using this API. The avatar is in base64 image format with the format data:image/png;base64, prepending it. Additionally, the metadata must conform to the scehema defined in the config.

// Example Request
{
    "avatar": "data:image/png;base64,iVBORw0KGgoAAA....",
    "name": {
        "first": "Bob",
        "last": "Smith"
    },
    "metadata": {}
}

Delete Profile

DELETE:/profile/ Client Basic Auth Required
Delete user's profile. This will remove all related user data including the metadata and sessions, while also loging out the user.

Add Email

POST:/profile/[email] Client Basic Auth Required
Add a new email address to your account.

// Example Request
// /profile/bob2@gmail.com

Remove Email

DELETE:/profile/[email] Client Basic Auth Required
Remove an email address from your account.

// Example Request
// /profile/bob2@gmail.com

Set Primary Email

POST:/profile/[email]/primary Client Basic Auth Required
Set a new primary email address for you account. Must be an already active email.

// Example Request
// /profile/bob2@gmail.com/primary

Verify New Email

POST:/profile/[email]/verify No Auth Required
Verify a new email address. Must pass the secret along in the body.

// Example Request
// /profile/bob2@gmail.com/verify
{
    "secret": "..."
}

Get Specific Users Profile

GET:/user/[id or email] Client Basic Auth Required
Get another user's profile by userID or email address. For example you could use either /user/f09496bc-ed7f-4e11-8f33-f610c5bbcabc or /user/bob@example.com.

// Example Response
{
    "id": "f09496bc-ed7f-4e11-8f33-f610c5bbcabc",
    "avatar": "data:image/png;base64,iVBORw0KGgoAAA....",
    "name": {
        "first": "Bob",
        "last": "Smith"
    },
    "email": {
        "primary": "bob@example.com",
        "active": [
            "bob@example.com"
        ],
        "pending": [{
            "email": "bob2@example.com",
            "update": "2023-10-13T01:22:33.352Z"
        }],
        "previous": [{
            "email": "notbob@example.com",
            "update": "2023-10-13T01:22:33.352Z"
        }]
    },
    "metadata": {}
}

Admin Get Settings

GET:/admin/settings Client Admin Auth Required or Machine Auth Required
Get the Authical settings. This includes branding, session config, and email templates.

// Example Response
{
    "branding": {
        "product": "Authical",
        "company": "Sellers LLC",
        "logo": "https://dummyimage.com/128x128/0475FF/FFFFFF/?text=%20%20Authical%20",
        "theme": {
            "light": {
                "primaryBackground": "#148FF5",
                "primaryForeground": "#FFFFFF",
                "secondaryBackground": "#000000",
                "secondaryForeground": "#FFFFFF"
            },
            "dark": {
                "primaryBackground": "#148FF5",
                "primaryForeground": "#FFFFFF",
                "secondaryBackground": "#FFFFFF",
                "secondaryForeground": "#000000"
            }
        },
        "authicalBranding": true
    },
    "admins": [],
    "account": {
        "whitelist": {
            "enable": false,
            "emails": []
        },
        "blacklist": {
            "enable": false,
            "emails": []
        },
        "ttl": {
            "otp": 600,
            "session": 2073600,
            "pendingEmail": 86400
        },
        "maxLoginAttempts": 3,
        "defaultAvatar": "data:image/png;base64,iVBORw0KGgoA...."
    },
    "emailTemplates": {
        "signup": {
            "title": "Welcome to {{branding.product}}! - One Time Password",
            "body": "...html..."
        },
        "signin": {
            "title": "Sign in to {{branding.product}}! - One Time Password",
            "body": "...html..."
        },
        "approveNewEmail": {
            "title": "Verify your email for {{branding.product}}",
            "body": "...html..."
        },
        "removeEmail": {
            "title": "Your email was removed for {{branding.product}}",
            "body": "...html..."
        },
        "changePrimaryEmail": {
            "title": "Your email was updated for {{branding.product}}",
            "body": "...html..."
        }
    }
}

Admin Update Settings

POST:/admin/settings Client Admin Auth Required or Machine Auth Required
Update the Authical settings. This includes branding, session config, and email templates. These settings must conform with the settings schema.

// Example Request
{
    "branding": {
        "product": "Authical",
        "company": "Sellers LLC",
        "logo": "https://dummyimage.com/128x128/0475FF/FFFFFF/?text=%20%20Authical%20",
        "theme": {
            "light": {
                "primaryBackground": "#148FF5",
                "primaryForeground": "#FFFFFF",
                "secondaryBackground": "#000000",
                "secondaryForeground": "#FFFFFF"
            },
            "dark": {
                "primaryBackground": "#148FF5",
                "primaryForeground": "#FFFFFF",
                "secondaryBackground": "#FFFFFF",
                "secondaryForeground": "#000000"
            }
        },
        "authicalBranding": true
    },
    "admins": [],
    "account": {
        "whitelist": {
            "enable": false,
            "emails": []
        },
        "blacklist": {
            "enable": false,
            "emails": []
        },
        "ttl": {
            "otp": 600,
            "session": 2073600,
            "pendingEmail": 86400
        },
        "maxLoginAttempts": 3,
        "defaultAvatar": "data:image/png;base64,iVBORw0KGgoA...."
    },
    "emailTemplates": {
        "signup": {
            "title": "Welcome to {{branding.product}}! - One Time Password",
            "body": "...html..."
        },
        "signin": {
            "title": "Sign in to {{branding.product}}! - One Time Password",
            "body": "...html..."
        },
        "approveNewEmail": {
            "title": "Verify your email for {{branding.product}}",
            "body": "...html..."
        },
        "removeEmail": {
            "title": "Your email was removed for {{branding.product}}",
            "body": "...html..."
        },
        "changePrimaryEmail": {
            "title": "Your email was updated for {{branding.product}}",
            "body": "...html..."
        }
    }
}

Admin Get Logs

GET:/admin/log Client Admin Auth Required or Machine Auth Required
Get logs from authical console about RESTful requests. Specify the log page with the URL paramater page. For example get the 1st page with /admin/log?page=0 and get the 10th page with /admin/log?page=9.

[
    {
        "timestamp": "2023-10-26T02:49:22.527Z",
        "event": "http://localhost:3000/admin/log?page=0",
        "message": "user: 97ce3baf-1460-462e-9fb6-55f7579c8c04, session: 97ce3baf-1460-462e-9fb6-55f7579c8c04"
    },
    {
        "timestamp": "2023-10-26T02:49:21.973Z",
        "event": "http://localhost:3000/admin/log?page=1",
        "message": "user: 97ce3baf-1460-462e-9fb6-55f7579c8c04, session: 97ce3baf-1460-462e-9fb6-55f7579c8c04"
    },
    {
        "timestamp": "2023-10-26T02:49:19.218Z",
        "event": "http://localhost:3000/admin/log?page=2",
        "message": "user: 97ce3baf-1460-462e-9fb6-55f7579c8c04, session: 97ce3baf-1460-462e-9fb6-55f7579c8c04"
    }
]

Admin Get Profile

GET:/admin/user/[id or email] Client Admin Auth Required or Machine Auth Required
Get user's profile by userID or email address. For example you could use either /user/f09496bc-ed7f-4e11-8f33-f610c5bbcabc or /user/bob@example.com. One notable difference between this API and Get Profile is that this API exposes the secrets for pending email addresses.

// Example Response
{
    "id": "f09496bc-ed7f-4e11-8f33-f610c5bbcabc",
    "avatar": "data:image/png;base64,iVBORw0KGgoAAA....",
    "name": {
        "first": "",
        "last": ""
    },
    "email": {
        "primary": "bob@example.com",
        "active": [
            "bob@example.com"
        ],
        "pending": [{
            "email": "bob2@example.com",
            "update": "2023-10-13T01:22:33.352Z",
            "secret": "HELLO"
        }],
        "previous": [{
            "email": "notbob@example.com",
            "update": "2023-10-13T01:22:33.352Z",
            "secret": "HELLO"
        }]
    },
    "isAdmin": false,
    "metadata": {}
}

Admin Update Profile

POST:/admin/user/[id or email] Client Admin Auth Required or Machine Auth Required
Update user's profile by userID or email address. For example you could use either /user/f09496bc-ed7f-4e11-8f33-f610c5bbcabc or /user/bob@example.com. You can the update any data you desire and it will override the stored data. The only requirement is that the data is valid profile schema and all the email addresses are available. The metadata provided must conform to metadata schema set by the config.

// Example Request
{
    "id": "f09496bc-ed7f-4e11-8f33-f610c5bbcabc",
    "avatar": "data:image/png;base64,iVBORw0KGgoAAA....",
    "name": {
        "first": "",
        "last": ""
    },
    "email": {
        "primary": "bob@example.com",
        "active": [
            "bob@example.com"
        ],
        "pending": [{
            "email": "bob2@example.com",
            "update": "2023-10-13T01:22:33.352Z",
            "secret": "werwer"
        }],
        "previous": [{
            "email": "notbob@example.com",
            "update": "2023-10-13T01:22:33.352Z",
            "secret": "werwer"
        }]
    },
    "metadata": {}
}

Admin Delete Profile

DELETE:/admin/user/[id or email] Client Admin Auth Required or Machine Auth Required
Delete user's profile. This will remove all related user data including the current OTPs and sessions, while also loging out the user.

Admin Get All Tokens

GET:/admin/token Client Admin Auth Required
Get all active API tokens. This is not accessable using a machine token.

// Example Response
[
    {
        "id": "ec0156fa-877a-4da0-b0d6-ac354c0f8483",
        "description": "The Test Token"
    },
    {
        "id": "fd822326-8b0b-4fef-971f-c4c5cf9a1e90",
        "description": "Test 2"
    }
]

Admin Add Token

GET:/admin/token Client Admin Auth Required
Get all active API tokens. This is not accessable using a machine token. Will return the new tokens ID and secret. This is the only time the token will be able to be accessed.

// Example Request
{
    "description": "The Test Token"
}

// Example Reponse
{
    "id": "fd822326-8b0b-4fef-971f-c4c5cf9a1e90",
    "secret": "...",
    "description": "The Test Token"
}

Admin Get Token

GET:/admin/token/[tokenID] Client Admin Auth Required
Get specific token by token ID. This is not accessable using a machine token.

// Example Reponse
{
    "id": "fd822326-8b0b-4fef-971f-c4c5cf9a1e90",
    "description": "The Test Token"
}

Admin Delete Token

DELETE:/admin/token/[tokenID] Client Admin Auth Required
Delete specific token by token ID. This is not accessable using a machine token.

// Example Request
// /admin/token/fd822326-8b0b-4fef-971f-c4c5cf9a1e90

Admin Session Verify

POST:/admin/session/verify Client Admin Auth Required or Machine Auth Required
Verify a user session by bearer token and return the UserID and the sessionID. If the session is not valid will return undefined.

// Example Request
{
    "bearer": "bearer ...."
}

// Example Reponse 1
undefined

// Example Response 2
[
    "userID",
    "sessionID"
]

About

Authical OTP -Backend

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages