Advanced Authentication#

Keywords: magic links, oauth2 github google, login token, api tokens, bearer token, social authentication

Asok provides built-in tools for modern authentication methods like Magic Links and OAuth2 (Google, GitHub, etc.) without adding extra framework-specific packages.

1. Magic Links (Passwordless)#

Magic Links allow users to log in securely using only their email address, without needing to remember a password.

Implementation#

Access the Magic Link helper via request.auth.magic.

Sending a Link#

In your login page action:

from asok import Request

def post(request: Request):
    email = request.form.get("email")
    if email:
        request.auth.magic.send(request, email)
        return "Check your email!"

Callback Handling#

Create a page at /auth/magic/callback.py:

from asok import Request

def get(request: Request):
    token = request.query.get("token")
    email = request.auth.magic.verify_token(request, token)

    if email:
        user = User.find(email=email)
        if not user:
            user = User.create(email=email)
        request.login(user)
        return request.redirect("/")

    return "Invalid or expired token."

2. OAuth2 (Social Login)#

Asok includes a standard-library implementation for OAuth2 providers.

Supported Providers#

• Google
• GitHub

Configuration#

You will need to pass your Client ID and Client Secret from the provider dashboard.

Step 1: Redirect to Provider#

from asok import Request

def get(request: Request):
    auth_url = request.auth.oauth.get_auth_url(
        provider_name="google",
        client_id="YOUR_CLIENT_ID",
        redirect_uri="https://myapp.com/auth/google/callback",
        state=request.session.get("oauth_state")
    )
    return request.redirect(auth_url)

Store the generated state value server-side and verify it in the callback before exchanging the authorization code.

Step 2: Handle Callback#

from asok import Request

def get(request: Request):
    code = request.query.get("code")
    user_info = request.auth.oauth.callback(
        provider_name="google",
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
        code=code,
        redirect_uri="https://myapp.com/auth/google/callback"
    )

    # user_info contains: email, name, picture, provider_id
    user = User.find(email=user_info["email"])
    if not user:
        user = User.create(email=user_info["email"], name=user_info["name"])

    request.login(user)
    return request.redirect("/")

3. API Tokens (Bearer Auth)#

Asok supports stateless API authentication via Bearer tokens. This is ideal for mobile apps or external integrations.

Usage#

Tokens are signed via the framework's SECRET_KEY, making them stateless and naturally secure.

Generating a Token#

from asok import Request

def get(request: Request):
    # Generate a permanent token for the current user
    token = request.auth.token.create(request, request.user.id)

    # Or generate a temporary token (e.g. 24 hours)
    token = request.auth.token.create(request, request.user.id, expires_in=86400)

    return request.api({"token": token})

Accessing your API#

Clients should send the token in the Authorization header: Authorization: Bearer <your-token>

Asok's request.user will automatically detect the token and authenticate the request.

# page/api/profile.py
from asok import Request

def get(request):
    if not request.user:
        return request.api_error("Unauthorized", status=401)

    return request.api({"email": request.user.email})

4. Roles & Permissions (RBAC)#

Asok includes a granular Role-Based Access Control system. While primarily used by the Admin Interface, it is available for use in any part of your application.

Permission Format#

Permissions are strings in the format slug.verb: - posts.view, posts.edit, users.delete - posts.* — all verbs for a specific model - * — superuser (all permissions)

Checking Permissions#

If your User model has a roles relationship (auto-provided by the Admin module), you can check permissions easily:

if request.user.can("posts.edit"):
    # Allow action
    pass

5. Two-Factor Authentication (2FA)#

Asok supports TOTP-based 2FA (compatible with Google Authenticator, Authy, etc.).

Enabling 2FA#

The built-in Admin interface provides a complete flow for enabling and verifying 2FA. See the Admin 2FA documentation for details.

Manual Implementation#

If you are building your own 2FA flow, you can use the underlying TOTP helpers (currently part of the asok.admin module).

Recommended flow:

1. Generate a TOTP secret for the user and store it server-side.
2. Display a QR code or provisioning URI once, during enrollment.
3. Require a successful code entry before marking totp_enabled = True.
4. Generate recovery codes and store only hashed versions.
5. Rate-limit verification attempts to reduce brute-force risk.

6. Security Notes#

• SECRET_KEY: All tokens are signed using the SECRET_KEY configured in your .env. Never share this key.
• Expiration: Magic Links expire in 1 hour by default.
• HTTPS: OAuth2 requires HTTPS for redirect URIs in production.
• State: Always generate and verify the OAuth state value to prevent CSRF.