reblocks-auth - A system to add an authentication to the Reblocks based web-site.

REBLOCKS-AUTH ASDF System Details

Description: A system to add an authentication to the Reblocks based web-site.
Licence: Unlicense
Author: Alexander Artemenko <svetlyak.40wt@gmail.com>
Homepage: https://40ants.com/reblocks-auth/
Bug tracker: https://github.com/40ants/reblocks-auth/issues
Source control: GIT
Depends on: alexandria, babel, cl-strings, dexador, ironclad, jonathan, local-time, log4cl, log4cl-extras, mailgun, mito, quri, reblocks, reblocks-lass, reblocks-ui, secret-values, serapeum, uuid, yason

Reblocks-auth is a system for adding authentication for your Reblocks application. It allows users to login using multiple ways. Right now GitHub is only supported but the list will be extended.

This system uses Mito as a storage to store data about users and their data from service providers. Each user has a unique nickname and an optional email. Also, one or more identity providers can be bound to each user account.

Installation

You can install this library from Quicklisp, but you want to receive updates quickly, then install it from Ultralisp.org:

(ql-dist:install-dist "http://dist.ultralisp.org/"
                      :prompt nil)
(ql:quickload :reblocks-auth)

Example App

I've made an example application to demonstrate how does reblocks-auth system work. To start this example application, run this code in the REPL:

(asdf:load-system :reblocks-auth-example)

(reblocks-auth-example/server:start :port 8080)

When you'll open the http://localhost:8080/ you will see this simple website:

Usage

This system provides a way for user authentifications. Each user is represented in the database using reblocks-auth/models:user model user can be bound to one or more "social profiles" - reblocks-auth/models:social-profile. For example, if user logged in via GitHub, then database will store one "user" record and one "social-profile" record. Each social profile can hold additional information in it's metadata slot.

To use this system, you have to define two routes which will be responsible for login and logout. On each route you have to render either reblocks-auth:login-processor or reblocks-auth:logout-processor widgets.

Usually you can define your routes like this (reblocks-navigation-widget:defroutes is used here):

(defroutes routes
    ("/" (make-page-frame
          (make-landing-page)))
  ("/login"
   (make-page-frame
    (reblocks-auth:make-login-processor)))
  ("/logout"
   (make-page-frame
    (reblocks-auth:make-logout-processor))))

This code will render a set up buttons to login through enabled service providers. Enabled service providers are listed in reblocks-auth:*enabled-services* variable.

renders buttons for enabled service providers calling reblocks-auth/button:render generic-function.
service processor is executed when user clicks a "login" button. For example GitHub processor redirects to https://github.com/login/oauth/authorize
when user comes back to /login page, service processor gets or creates entries in the database and stores current user in the session.
after this, any code can retrieve current user by a call to reblocks-auth/models:get-current-user.

Logout processor renders a "logout" button and when user clicks on it, removes user from the current session.

Telegram Authentication

Telegram authentication uses the Telegram Login Widget. When a user clicks the widget, Telegram opens a confirmation dialog and then redirects back to your server with signed user data. The server verifies the HMAC-SHA256 signature using the bot token before accepting the login.

Setting Up a Bot

Open @BotFather in Telegram and send /newbot.
After the bot is created, send /setdomain and enter your website's domain (e.g. example.com). Telegram will reject logins from any other domain.
Copy the bot username (without @) and the bot token shown by BotFather.

Configuration

(setf reblocks-auth/providers/telegram:*bot-username* "MyAppBot")
(setf reblocks-auth/providers/telegram:*bot-token*
      (secret-values:conceal-value "123456:ABC-DEF..."))

(pushnew :telegram reblocks-auth:*enabled-services*)

Two variables control the provider:

reblocks-auth/providers/telegram:*bot-username* — the bot username registered with BotFather (used to render the widget).
reblocks-auth/providers/telegram:*bot-token* — the bot token used server-side to verify the authentication hash. Never expose this value to the browser. Accepts a plain string or a secret-values:secret-value.

The widget script is rendered as a <script> tag with data-auth-url pointing to /login?service=telegram.
When a user clicks the widget, Telegram opens a confirmation dialog.
On success Telegram appends id, first_name, last_name, username, photo_url, auth_date, and hash to the data-auth-url and redirects the browser there.
The login-processor widget picks up the service=telegram parameter and calls reblocks-auth/auth:authenticate.
The server verifies the HMAC-SHA256 signature and checks that auth_date is no older than 24 hours.
The user record is looked up or created and stored in the session.

Testing on Localhost

Telegram requires a real public domain — localhost is not accepted. For local development, expose your server with a tunneling tool and register that domain with BotFather:

# ngrok (free tier gives a random HTTPS URL each run)
ngrok http 8080

# localtunnel (fixed subdomain)
npx localtunnel --port 8080 --subdomain myapp

Then in BotFather send /setdomain with the tunnel hostname (e.g. myapp.loca.lt). Open the app through the tunnel URL rather than localhost:8080.

Yandex SmartCaptcha Support

Yandex SmartCaptcha provides an alternative to Google reCAPTCHA for protecting the email-based authentication form.

Quick Start

To enable Yandex SmartCaptcha, set following variables:

(setf reblocks-auth/providers/email/processing:*smartcaptcha-client-key* "your-client-key")
(setf reblocks-auth/providers/email/processing:*smartcaptcha-server-key* "your-server-key")

Getting Yandex SmartCaptcha Keys

Go to Yandex Cloud Console
Navigate to SmartCaptcha service
Create a new SmartCaptcha site
Copy Client key (for frontend) and Server key (for backend)
Add keys to your application configuration

How It Works

User clicks "Email" login button
JavaScript loads https://smartcaptcha.yandexcloud.net/captcha.js
User solves captcha (automatic or manual)
Token is generated and sent to backend
Backend validates token via https://smartcaptcha.yandexcloud.net/validate
Email with login code is sent
User enters code to complete authentication

Multiple Captcha Providers

Yandex SmartCaptcha takes precedence when both Yandex SmartCaptcha and Google reCAPTCHA are configured.

If only Google reCAPTCHA is configured, it will be used.

Verification

The server validates the captcha token via the verify-smartcaptcha function, which POSTs the token and server key to Yandex's validation endpoint.

Successful validation returns {"status": "ok"}. Failed validation returns {"status": "error"}.