How do I install the Admin Auth Guide skill?

Run npx skillmds@latest add aibot88/admin-auth-guide in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Admin Auth Guide safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Admin Auth Guide?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Admin Auth Guide free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Admin Auth Guide?

aibot88 (@aibot88) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Admin Auth Guide by aibot88 — Agent Skill

Name: Admin Auth Guide
Rating: 4.2 (5 reviews)
Author: aibot88

File contents

Admin Auth & Authorization Guide

Authentication Flow

Step 1: Telegram Login

User clicks "Login with Telegram" widget
Frontend sends Telegram init_data to Login Backend (:8082)
Login Backend validates hash signature against bot token
Extracts tg_id from init_data

Step 2: First-Time Setup

If admin user has no TOTP configured:

Generate TOTP secret (encrypted with AES-GCM, key from LOGIN_TOTP_SECRET_KEY)
Return QR code + recovery codes to frontend
User scans QR in authenticator app
User confirms with TOTP code
User sets initial password (bcrypt hashed)

Step 3: Returning Login

Verify TOTP code (6-digit)
Verify password (bcrypt)
Issue JWT token

Step 4: JWT Token

Claims:

{
  "sub": "admin_user_uuid",
  "sid": "session_uuid",
  "role": "admin|superadmin|...",
  "exp": "...",
  "iat": "..."
}

Signed with LOGIN_JWT_SECRET (must match ADMIN_WEB_JWT_SECRET in backend)
Frontend stores in memory/localStorage

Step 5: Session Management

Server-side session in admin_sessions table
Session has idle timeout (ADMIN_WEB_SESSION_IDLE_TIMEOUT, default 30m)
Session has max lifetime (LOGIN_SESSION_MAX_LIFETIME, default 12h)
Each API request refreshes idle timeout
Session deleted on logout

Backend Auth Middleware

AdminWebAuthMiddleware

Location: backend/internal/transport/http/middleware/

Extract Authorization: Bearer <token> header
Validate JWT signature and expiration
Extract sid claim
Check session exists in admin_sessions table
Check session not expired (idle + max lifetime)
Refresh idle timeout
Set identity in request context

RequireAdminRoleOrPermission

Location: backend/internal/app/apiapp/routes.go

Two modes (ADMIN_AUTHZ_MODE):

dual: check legacy role allowlist OR permission-based access
permission_only: only check permissions (target mode)

Permissions are granular: view_metrics, export_data, manage_users, moderate_content, manage_access, manage_settings, etc.

Key Files

File	Purpose
`adminpanel/backend/login/`	Login backend service
`backend/internal/services/adminacl/`	Admin ACL service
`backend/internal/repo/postgres/admin_session_repo.go`	Session repository
`backend/internal/transport/http/middleware/`	Auth middleware
`adminpanel/frontend/src/admin/`	Frontend auth layer
`adminpanel/frontend/src/lib/adminAuthApi.ts`	Auth API client
`adminpanel/frontend/src/pages/LoginPage.tsx`	Login UI

Environment Variables

# Login Backend
LOGIN_JWT_SECRET=<shared-with-backend>
LOGIN_TOTP_SECRET_KEY=<base64-32-byte-AES-key>
LOGIN_TELEGRAM_BOT_TOKEN=<telegram-bot-token>
LOGIN_SESSION_IDLE_TIMEOUT=30m
LOGIN_SESSION_MAX_LIFETIME=12h
LOGIN_DEV_MODE=true  # enables debug init_data login

# Backend
ADMIN_WEB_JWT_SECRET=<must-match-LOGIN_JWT_SECRET>
ADMIN_WEB_SESSION_IDLE_TIMEOUT=30m
ADMIN_AUTHZ_MODE=dual  # or permission_only

---name: admin-auth-guidedescription: Admin authentication and authorization system reference — login flow, JWT, TOTP, sessions, RBAC--- # Admin Auth & Authorization Guide ## Authentication Flow ### Step 1: Telegram Login - User clicks "Login with Telegram" widget - Frontend sends Telegram `init_data` to Login Backend (:8082) - Login Backend validates hash signature against bot token - Extracts `tg_id` from init_data ### Step 2: First-Time Setup If admin user has no TOTP configured: 1. Generate TOTP secret (encrypted with AES-GCM, key from `LOGIN_TOTP_SECRET_KEY`) 2. Return QR code + recovery codes to frontend 3. User scans QR in authenticator app 4. User confirms with TOTP code 5. User sets initial password (bcrypt hashed) ### Step 3: Returning Login 1. Verify TOTP code (6-digit) 2. Verify password (bcrypt) 3. Issue JWT token ### Step 4: JWT Token Claims: ```json { "sub": "admin_user_uuid", "sid": "session_uuid", "role": "admin|superadmin|...", "exp": "...", "iat": "..." } ``` - Signed with `LOGIN_JWT_SECRET` (must match `ADMIN_WEB_JWT_SECRET` in backend) - Frontend stores in memory/localStorage ### Step 5: Session Management - Server-side session in `admin_sessions` table - Session has idle timeout (`ADMIN_WEB_SESSION_IDLE_TIMEOUT`, default 30m) - Session has max lifetime (`LOGIN_SESSION_MAX_LIFETIME`, default 12h) - Each API request refreshes idle timeout - Session deleted on logout ## Backend Auth Middleware ### AdminWebAuthMiddleware Location: `backend/internal/transport/http/middleware/` 1. Extract `Authorization: Bearer <token>` header 2. Validate JWT signature and expiration 3. Extract `sid` claim 4. Check session exists in `admin_sessions` table 5. Check session not expired (idle + max lifetime) 6. Refresh idle timeout 7. Set identity in request context ### RequireAdminRoleOrPermission Location: `backend/internal/app/apiapp/routes.go` Two modes (`ADMIN_AUTHZ_MODE`): - **dual**: check legacy role allowlist OR permission-based access - **permission_only**: only check permissions (target mode) Permissions are granular: `view_metrics`, `export_data`, `manage_users`, `moderate_content`, `manage_access`, `manage_settings`, etc. ## Key Files | File | Purpose | |------|---------| | `adminpanel/backend/login/` | Login backend service | | `backend/internal/services/adminacl/` | Admin ACL service | | `backend/internal/repo/postgres/admin_session_repo.go` | Session repository | | `backend/internal/transport/http/middleware/` | Auth middleware | | `adminpanel/frontend/src/admin/` | Frontend auth layer | | `adminpanel/frontend/src/lib/adminAuthApi.ts` | Auth API client | | `adminpanel/frontend/src/pages/LoginPage.tsx` | Login UI | ## Environment Variables ```bash # Login Backend LOGIN_JWT_SECRET=<shared-with-backend> LOGIN_TOTP_SECRET_KEY=<base64-32-byte-AES-key> LOGIN_TELEGRAM_BOT_TOKEN=<telegram-bot-token> LOGIN_SESSION_IDLE_TIMEOUT=30m LOGIN_SESSION_MAX_LIFETIME=12h LOGIN_DEV_MODE=true # enables debug init_data login # Backend ADMIN_WEB_JWT_SECRET=<must-match-LOGIN_JWT_SECRET> ADMIN_WEB_SESSION_IDLE_TIMEOUT=30m ADMIN_AUTHZ_MODE=dual # or permission_only ```

Frequently asked questions

Admin Auth Guide