Мне кажется, что уже есть сотни разных статей на эту тему, но каждый раз мне чего-то не хватало. Поэтому я решил написать свою статью, в которой покажу, как я реализую авторизацию и аутентификацию в своих проектах. Это именно гайд: вы можете взять готовый код и адаптировать его под свои нужды. В рамках статьи будут использоваться Ory Hydra и Ory Kratos, Apache APISIX в качестве API Gateway и несколько микросервисов на Golang. Всё это будет работать в Docker, чтобы вы могли легко запустить и поиграться.
На теорию много времени тратить не буду, можете посмотреть несколько статей по ссылкам ниже:
Сначала я хотел показать всё в рамках Kubernetes, но потом решил, что это будет излишне сложно в рамках статьи, поэтому
покажу на примере простого docker-compose, чтобы каждый мог легко запустить.
В рамках статьи я иду на определённые упрощения, например, использую стандартные пароли, не использую https и т.д. Это сделано для того, чтобы вы могли легко запустить и протестировать систему. В реальных проектах, конечно же, так делать не нужно.
Архитектура
Если с аутентификацией всё более-менее понятно, то с авторизацией всё сложнее. Можно выделить несколько основных сценариев работы:
Используем простые, статичные роли, которые редко меняются. Например,
admin,user,guestи т.д.Нужен больший контроль и динамическое управление доступом, например, разрешения на определенные действия для разных ролей. И делать все атомарно. Тогда у нас появляется дополнительный уровень - разрешения/права, которые назначаются в рамках микросервиса, а потом назначаются на конкретные роли. Здесь уже явно нужен отдельный сервис, как минимум для централизованного управления, но всё ещё не требуется специализированная система.
Нужна сложная система управления доступом, которая может включать в себя RBAC (Role-Based Access Control) или ABAC (Attribute-Based Access Control). Это уже сложные системы, которые требуют отдельного сервиса для управления доступом и могут быть избыточными для большинства проектов.
С третьим всё сложно, но есть готовые решения (например, Casbin, Ory Keto и т.д.), которые можно использовать. Правда, это не гарантия того, что установите и поедете. Мы в своё время испугались использовать Casbin и правильно сделали. Всё решилось гораздо проще.
А вот первое и второе мы разберём в рамках этой статьи. Для реализации первых двух вариантов, кажется, что проще всего использовать JWT (JSON Web Token). Но это не совсем так. JWT имеет ограничение, точнее не столько он, сколько информация, передаваемая в заголовке. Если правильно помню — NGINX/Apache имеют лимит
в 8кб на заголовок, а это значит, что мы не можем хранить слишком много информации в JWT. То есть если для первого варианта он однозначно подойдёт, то для второго варианта уже будет зависеть от того, насколько атомарно мы делим и
сколько у нас микросервисов. Потому что если у нас 100 микросервисов, в каждом из которых будет свой scope на каждую CRUD ручку (news:read, order:create и т.д.), то выйдет примерно 4.88 килобайт, что уже близко к лимиту, а у нас в заголовках не только JWT.
Поэтому для первого варианта мы будем использовать JWT, а для второго варианта — будем использовать opaque токены и обращаться в сервис для получения информации о пользователе и его разрешениях. Это позволит нам избежать проблем с размером
заголовка и упростит управление доступом. Но, как можно понять, это добавит некоторые накладные расходы, но мы их сгладим за счёт кэширования на время жизни токена на стороне API Gateway. Он будет отвечать за проверку токена и ролей.
В первом случае у нас будет следующий путь:
Пользователь проходит аутентификацию через отдельный сервис.
Сервис аутентификации выдаёт JWT токен, который содержит информацию о пользователе и его ролях.
Пользователь отправляет запросы к микросервисам, передавая JWT токен в заголовке Authorization.
Запрос проходит через API Gateway, который проверяет JWT токен и извлекает информацию о пользователе.
API Gateway проверяет, есть ли у пользователя нужная роль, с которой можно в микросервис, и перенаправляет запрос к нужному микросервису.
Микросервис выполняет действие и возвращает ответ. В рамках самого микросервиса проверки уже не делаем.
Во втором случае у нас будет похожий путь, но вместо JWT мы выдаём opaque токен, в API Gateway также проверяем роли после запроса к сервису аутентификации, а на микросервисах добавляем middleware, который будет проверять разрешения на ручках.
Давайте выберем и поднимем всю необходимую инфраструктуру, чтобы у нас была возможность протестировать оба варианта.
Система авторизации/аутентификации
В качестве системы мы можем написать свой сервис, но с учётом огромного количества готовых решений, я думаю, что лучше использовать готовое решение, которое можно легко интегрировать в нашу архитектуру.
Я думаю, что многие хоть раз слышали о Keycloak. Он надёжен, стабилен и имеет много
возможностей, но у него есть пара недостатков:
Это довольно большой комбайн, который может быть избыточным.
У него монолитная архитектура, что может усложнить масштабирование и поддержку. Но самое главное в этом — если вы не знаете Java, то вам будет сложно его настраивать и поддерживать. Даже банально сделать свою страницу входа — уже не просто.
Ок, мы понимаем, что нам нужно что-то простое и гибкое. В идеале — что-то, что можно легко развернуть и настроить, API-first. Стек должен быть доступным, чтобы иметь возможность, например, написать своего провайдера. Также одним из требований — развертывание в нашей инфраструктуре, а не в облаке. И тут остаётся много вариантов, но я вначале остановился на нескольких:
Ory Hydra / Ory Kratos — микросервисная архитектура с четким разделением ответственности. Написан на Go, хорошо документирован. Зрелый проект с консервативным подходом к релизам (2 релиза в год). Используется в OpenAPI Initiative, что говорит о надежности. 12к звезд на GitHub. Kratos управляет идентичностями и аутентификацией, Hydra — OAuth2/OIDC провайдер.
Casdoor — простой старт "из коробки" с готовыми React-компонентами. Поддерживает все популярные методы аутентификации, включая социальные сети. Написан на Go, легко расширяется кастомными провайдерами. 11к звезд на GitHub. Из минусов - частые релизы усложняют поддержку, медленное исправление уязвимостей, переусложненный UI для управления ролями. Команда сейчас фокусируется на SaaS-решении, что может повлиять на open-source версию.
Authelia — зрелое решение с сертификацией OpenID Connect. Сильное комьюнити (24к звезд), хорошая интеграция с reverse proxy (Nginx, Traefik).
В рамках статьи я буду использовать Ory Hydra/Kratos, просто потому что хочу его пощупать. Для этого и нужны статьи:)
Для продакшена каждый выбирает инструмент под свои задачи и свой стек. А эта статья поможет вам поэкспериментировать, прежде чем выбрать инструмент для своей системы.
Давайте поднимем Ory Kratos в docker-compose. Для этого создадим файл docker-compose.yml:
docker-compose.yml
services:
# Migration service for Kratos
kratos-migrate:
image: oryd/kratos:v1.3.1
environment:
- DSN=postgres://kratos:secret@kratos-pg:5432/kratos?sslmode=disable&max_conns=20&max_idle_conns=4
volumes:
- type: bind
source: ./docker/kratos/configs
target: /etc/config/kratos
depends_on:
- kratos-pg
command: -c /etc/config/kratos/kratos.yml migrate sql -e --yes
restart: on-failure
networks:
- intranet
# Postgres database for Kratos
kratos-pg:
image: postgres:17
environment:
- POSTGRES_USER=kratos
- POSTGRES_PASSWORD=secret
- POSTGRES_DB=kratos
healthcheck:
test: [ "CMD-SHELL", "pg_isready -U kratos" ]
networks:
- intranet
# Example selfservice UI for Kratos. Just a simple Node.js app that uses Kratos for authentication.
kratos-selfservice-ui-node:
image: oryd/kratos-selfservice-ui-node:v1.3.1
ports:
- "4455:3000"
environment:
- KRATOS_PUBLIC_URL=http://kratos:4433/
- KRATOS_BROWSER_URL=http://127.0.0.1:4433/
- COOKIE_SECRET=changeme
- CSRF_COOKIE_NAME=ory_csrf_ui
- CSRF_COOKIE_SECRET=changeme
networks:
- intranet
restart: on-failure
# Ory Kratos service
kratos:
depends_on:
- kratos-migrate
image: oryd/kratos:v1.3.1
ports:
- '4433:4433' # public
- '4434:4434' # admin
restart: unless-stopped
environment:
- DSN=postgres://kratos:secret@kratos-pg:5432/kratos?sslmode=disable&max_conns=20&max_idle_conns=4
- LOG_LEVEL=trace
command: serve -c /etc/config/kratos/kratos.yml --dev --watch-courier
volumes:
- type: bind
source: ./docker/kratos/configs
target: /etc/config/kratos
networks:
- intranet
# Mail service for testing email flows
mailslurper:
image: oryd/mailslurper:latest-smtps
ports:
- '4436:4436' # Email UI
networks:
- intranet
networks:
intranet:После чего можем зайти в веб-интерфейс по адресу http://127.0.0.1:4455 и зарегистрировать нового пользователя.
Тут важно использовать именно 127.0.0.1, а не localhost. После того как зайдете под новым пользователем, можете увидеть информацию о пользователе, попробовать поменять и подключить 2FA.
Первый шаг сделан, теперь у нас есть сервис аутентификации, но для реализации авторизации нужен Oauth. Давайте добавим сервис в нашу систему. Для этого мы будем использовать Ory Hydra, который будет работать с Ory Kratos для аутентификации пользователей. Ory Hydra будет выступать в роли OAuth2 провайдера, который будет выдавать токены доступа. Это позволит нам централизованно управлять доступом к ресурсам и сервисам в нашей микросервисной архитектуре.
Добавим Ory Hydra в наш docker-compose.yml:
docker-compose.yml
# Ory Hydra migration service
hydra-migrate:
image: oryd/hydra:v2.3.0
depends_on:
- hydra-pg
environment:
- DSN=postgres://hydra:secret@hydra-pg:5432/hydra?sslmode=disable
command: migrate -c /etc/config/hydra/hydra.yml sql up -e --yes
volumes:
- type: bind
source: ./docker/hydra/config
target: /etc/config/hydra
networks:
- intranet
restart: on-failure
# Ory Hydra Postgres database
hydra-pg:
image: postgres:17
environment:
- POSTGRES_USER=hydra
- POSTGRES_PASSWORD=secret
- POSTGRES_DB=hydra
healthcheck:
test: [ "CMD-SHELL", "pg_isready -U hydra" ]
networks:
- intranet
# Ory Hydra service
hydra:
image: oryd/hydra:v2.3.0
depends_on:
- hydra-migrate
ports:
- "4444:4444" # Public
- "4445:4445" # Admin
environment:
- DSN=postgres://hydra:secret@hydra-pg:5432/hydra?sslmode=disable
volumes:
- type: bind
source: ./docker/hydra/config
target: /etc/config/hydra
command: serve -c /etc/config/hydra/hydra.yml all --dev
networks:
- intranet
restart: unless-stoppedТеперь Ory Hydra запущен и готов к работе. Можем легко проверить, если перейдем по адресу http://127.0.0.1:4444/health/ready.
Ory из коробки поддерживает экспорт метрик в Prometheus и трейсы в Jaeger, поэтому вы можете легко интегрировать их. Если не знакомы, можете почитать цикл моих статей и воспользоваться готовым репозиторием - вам будет достаточно добавить конфигурацию для новых сервисов и все будет работать. В рамках этой статьи сюда углубляться не буду.
Как я создавал Observability для своих pet-проектов. Часть 1
Микросервисы
Теперь давайте создадим несколько микросервисов на Golang, в рамках которых будем проверять разрешения на определенные действия. Пока сделаем простые CRUD сервисы, которые будут отдавать нам определенное сообщение и все. Логику будем делать позже, только в рамках проверки разрешений.
У нас будут следующие условные микросервисы:
users- сервис для работы с пользователями.products- сервис для работы с продуктами.orders- сервис для работы с заказами.
Все сервисы будут в папке cmd, всю нашу "логику" будем писать в рамках одного main.go файла, что бы не усложнять. main.go будет выглядеть следующим образом для каждого из сервисов:
main.go
package main
import (
"fmt"
"log"
"net/http"
"os"
"github.com/gorilla/mux"
)
func main() {
r := mux.NewRouter()
service := os.Getenv("SERVICE_NAME")
r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello from %s service!", service)
}).Methods("GET")
r.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Create in %s service!", service)
}).Methods("POST")
r.HandleFunc("/{id}", func(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
fmt.Fprintf(w, "Read %s with id %s!", service, vars["id"])
}).Methods("GET")
r.HandleFunc("/{id}", func(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
fmt.Fprintf(w, "Update %s with id %s!", service, vars["id"])
}).Methods("PUT")
r.HandleFunc("/{id}", func(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
fmt.Fprintf(w, "Delete %s with id %s!", service, vars["id"])
}).Methods("DELETE")
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
log.Printf("Starting %s service on port %s", service, port)
log.Fatal(http.ListenAndServe(":"+port, r))
}Теперь давайте создадим простой Dockerfile для каждого из сервисов, что бы мы могли их собрать и запустить в Docker:
FROM golang:1.24-alpine AS builder
WORKDIR /build
COPY ./go.mod ./go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-w -s" -o products cmd/products/main.go
FROM alpine:latest
RUN apk --no-cache add ca-certificates && \
addgroup -S appgroup && adduser -S appuser -G appgroup \
COPY --from=builder /build/products /app/products
USER appuser
WORKDIR /app
EXPOSE 8080
ENTRYPOINT ["/app/products", "sync", "-d"]И добавляем наши сервисы в docker-compose.yml:
docker-compose.yml
users:
build:
context: .
dockerfile: users.Dockerfile
environment:
- SERVICE_NAME=users
- PORT=8080
ports:
- "8081:8080"
networks:
- intranet
products:
build:
context: .
dockerfile: products.Dockerfile
environment:
- SERVICE_NAME=products
- PORT=8080
ports:
- "8082:8080"
networks:
- intranet
orders:
build:
context: .
dockerfile: orders.Dockerfile
environment:
- SERVICE_NAME=orders
- PORT=8080
ports:
- "8083:8080"
networks:
- intranetПосле чего запускаем и пробуем постучать на один из сервисов -http://127.0.1:8081/. Получаем ответ "Hello from users service!". Теперь осталось настроить последний сервис - API Gateway, который будет интегрирован с Ory Hydra и Ory Kratos.
Настройка API Gateway
Теперь, когда у нас есть сервисы аутентификации и авторизации, давайте настроим API Gateway, который будет интегрирован с Ory Hydra и Ory Kratos. В качестве API Gateway чаще всего используют Kong, но мне хочется попробовать что-то новое, поэтому я выбрал Apache APISIX.
Добавляем его в наш docker-compose.yml:
docker-compose.yml
etcd:
image: bitnami/etcd:3.5
environment:
- ALLOW_NONE_AUTHENTICATION=yes
- ETCD_ADVERTISE_CLIENT_URLS=http://0.0.0.0:2379
networks:
- intranet
apisix:
image: apache/apisix
depends_on:
- etcd
ports:
- "9080:9080" # HTTP endpoint
- "9180:9180" # Admin-API
volumes:
- ./docker/apisix/config.yaml:/usr/local/apisix/conf/config.yaml
environment:
- APISIX_ENABLE_ADMIN=true
- APISIX_ADMIN_KEY=supersecret
- APSIX_ETCD_HOST=http://etcd:2379
networks:
- intranet
apisix-dashboard:
image: apache/apisix-dashboard
depends_on:
- apisix
ports:
- "9000:9000"
volumes:
- ./docker/apisix_dashboard_conf/config.yaml:/usr/local/apisix-dashboard/conf/conf.yaml
environment:
- DEFAULT_APISIX_ADMIN_KEY=supersecret
- APISIX_LISTEN_ADDRESS=http://apisix:9091
networks:
- intranetДелаем два конфиг файла для APISIX и APISIX Dashboard, что бы настроить их под себя.
Создадим файл docker/apisix/config.yaml:
apisix:
enable_admin: true
admin_key:
- name: admin
key: supersecret
allow_admin:
- 0.0.0.0/0
deployment:
role: traditional
admin:
admin_listen:
port: 9180
allow_admin:
- 0.0.0.0/0
etcd:
host:
- "http://etcd:2379"
prefix: "/apisix"
timeout: 30И файл docker/apisix_dashboard_conf/config.yaml:
conf:
listen:
port: 9000
etcd:
endpoints:
- etcd:2379
authentication:
secert: secert
expire_time: 3600
users:
- username: admin
password: adminОткрываем веб-интерфейс APISIX Dashboard по адресу http://127.0.0.1:9000, вводим логин и пароль admin/admin.
Создаем страницу для получения токена
kratos-selfservice-ui-node - который мы подняли ранее, не умеет работать с Ory Hydra, он отвечает только за аутентификацию и регистрацию пользователей. Поэтому нам нужно создать страницу, которая будет работать с Ory Hydra и получать токен доступа. Для этого мы создадим простую страницу на Node.js, которая будет использовать Ory Hydra для получения токена доступа. Эта страница будет использоваться для получения токена доступа и перенаправления пользователя на страницу Kratos Selfservice UI для аутентификации. Создадим папку docker/hydra и файл index.js в ней:
JS
const express = require('express');
const axios = require('axios');
const crypto = require('crypto');
const session = require('express-session');
const app = express();
const port = 3001;
// Settings - explicitly specify IPv4 addresses
const HYDRA_PUBLIC_URL = process.env.HYDRA_PUBLIC_URL || 'http://127.0.0.1:4444'; // For browser
const HYDRA_INTERNAL_URL = process.env.HYDRA_INTERNAL_URL || 'http://hydra:4444'; // For internal requests from container
const HYDRA_ADMIN_URL = process.env.HYDRA_ADMIN_URL || 'http://hydra:4445'; // IPv4 for admin API
const CLIENT_ID = process.env.CLIENT_ID || 'web';
const CLIENT_SECRET = process.env.CLIENT_SECRET || 'web-secret';
const REDIRECT_URI = process.env.REDIRECT_URI || 'http://127.0.0.1:3001/callback';
const APP_URL = process.env.APP_URL || 'http://127.0.0.1:3001';
console.log('App settings:');
console.log('HYDRA_PUBLIC_URL:', HYDRA_PUBLIC_URL);
console.log('HYDRA_INTERNAL_URL:', HYDRA_INTERNAL_URL);
console.log('HYDRA_ADMIN_URL:', HYDRA_ADMIN_URL);
console.log('CLIENT_ID:', CLIENT_ID);
console.log('REDIRECT_URI:', REDIRECT_URI);
console.log('APP_URL:', APP_URL);
app.use(session({
secret: 'your-session-secret',
resave: false,
saveUninitialized: true,
cookie: {
secure: false,
httpOnly: true,
sameSite: 'lax',
maxAge: 60 * 60 * 1000 // 1 hour
}
}));
app.use(express.urlencoded({extended: true}));
app.use(express.json());
// Middleware for debugging cookies and sessions
app.use((req, res, next) => {
console.log(`${req.method} ${req.path}`, {
sessionID: req.sessionID,
cookies: req.headers.cookie,
session: req.session
});
next();
});
// ============= OAuth2 Client part =============
// Main page
app.get('/', (req, res) => {
const token = req.session.token;
const loginChallenge = req.query.login_challenge;
const loginError = req.query.error;
// If there is a login_challenge, show the login form
if (loginChallenge) {
return res.send(`
<!DOCTYPE html>
<html>
<head>
<title>Login - OAuth2</title>
<style>
body { font-family: Arial, sans-serif; max-width: 400px; margin: 100px auto; padding: 20px; }
.container { background: white; padding: 30px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); }
h2 { color: #333; margin-bottom: 20px; }
input { width: 100%; padding: 10px; margin: 10px 0; border: 1px solid #ddd; border-radius: 4px; box-sizing: border-box; }
button { width: 100%; background: #007bff; color: white; padding: 12px; border: none; border-radius: 4px; cursor: pointer; font-size: 16px; }
button:hover { background: #0056b3; }
.info { background: #f8f9fa; padding: 15px; border-radius: 4px; margin-bottom: 20px; font-size: 14px; }
.error { background: #f8d7da; color: #721c24; padding: 15px; border-radius: 4px; margin-bottom: 20px; font-size: 14px; }
</style>
</head>
<body>
<div class="container">
<h2>Login</h2>
${loginError ? `<div class="error">${loginError}</div>` : ''}
<form method="POST" action="/auth/login">
<input type="hidden" name="challenge" value="${loginChallenge}">
<input type="email" name="email" placeholder="Email" value="test@example.com" required>
<input type="password" name="password" placeholder="Password" required>
<button type="submit">Login</button>
</form>
</div>
</body>
</html>
`);
}
// Regular main page
let content = `
<!DOCTYPE html>
<html>
<head>
<title>OAuth2 Demo</title>
<style>
body { font-family: Arial, sans-serif; max-width: 800px; margin: 50px auto; padding: 20px; }
.container { background: white; padding: 30px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
.button { background: #007bff; color: white; padding: 12px 24px; border: none; border-radius: 4px; cursor: pointer; }
.button:hover { background: #0056b3; }
.token-info { background: #f8f9fa; padding: 20px; margin-top: 20px; border-radius: 4px; }
pre { white-space: pre-wrap; word-wrap: break-word; }
input { width: 100%; padding: 10px; margin: 10px 0; border: 1px solid #ddd; border-radius: 4px; }
.success { background: #d4edda; color: #155724; padding: 15px; border-radius: 4px; margin: 10px 0; }
</style>
</head>
<body>
<div class="container">
<h1>OAuth2 Demo Application</h1>`;
if (token) {
// Decode JWT
let claims = {};
try {
const parts = token.access_token.split('.');
if (parts.length === 3) {
claims = JSON.parse(Buffer.from(parts[1], 'base64').toString());
}
} catch (e) {
// Opaque token
}
content += `
<div class="success">
<h3>✅ You are logged in!</h3>
</div>
<div class="token-info">
<p><strong>Access Token:</strong></p>
<pre>${token.access_token}</pre>
<p><strong>Token Type:</strong> ${token.token_type}</p>
<p><strong>Expires In:</strong> ${token.expires_in} seconds</p>
${token.refresh_token ? `<p><strong>Refresh Token:</strong></p><pre>${token.refresh_token}</pre>` : ''}
${claims.sub ? `
<hr>
<h4>Information from token:</h4>
<p><strong>User ID:</strong> ${claims.sub}</p>
<p><strong>Email:</strong> ${claims.ext.traits?.email || 'N/A'}</p>
<p><strong>Roles:</strong> ${JSON.stringify(claims.ext.traits?.roles || [])}</p>
<p><strong>Scope:</strong> ${JSON.stringify(claims.scp)}</p>
<p><strong>Issued At:</strong> ${new Date(claims.iat * 1000).toLocaleString()}</p>
<p><strong>Expires At:</strong> ${new Date(claims.exp * 1000).toLocaleString()}</p>
` : ''}
</div>
<form action="/logout" method="post" style="margin-top: 20px;">
<button type="submit" class="button" style="background: #dc3545;">Logout</button>
</form>`;
} else {
content += `
<p>This is a demo application for testing OAuth2 flow with Ory Hydra.</p>
<p>Click the button below to start the authorization process.</p>
<form action="/start-oauth" method="post">
<label>Scopes (separated by space):</label>
<input name="scope" value="openid offline users:read products:read orders:read" />
<button type="submit" class="button">Start OAuth2 Authorization</button>
</form>`;
}
content += `
</div>
</body>
</html>`;
res.send(content);
});
// Start OAuth2 flow
app.post('/start-oauth', (req, res) => {
const scope = req.body.scope || 'openid offline';
const state = crypto.randomBytes(16).toString('hex');
const verifier = crypto.randomBytes(32).toString('base64url');
const challenge = crypto
.createHash('sha256')
.update(verifier)
.digest('base64url');
// Save in session
req.session.oauth = {state, verifier};
req.session.save((err) => {
if (err) {
console.error('Session save error:', err);
}
});
console.log('Starting OAuth flow:', {
state,
sessionID: req.sessionID,
session: req.session
});
// Redirect to Hydra
const params = new URLSearchParams({
client_id: CLIENT_ID,
redirect_uri: REDIRECT_URI,
response_type: 'code',
scope: scope,
state: state,
code_challenge: challenge,
code_challenge_method: 'S256'
});
const authUrl = `${HYDRA_PUBLIC_URL}/oauth2/auth?${params}`;
console.log('Redirecting to:', authUrl);
res.redirect(authUrl);
});
// OAuth2 callback
app.get('/callback', async (req, res) => {
const {code, state, error, error_description} = req.query;
console.log('Callback received:', {code: code?.substring(0, 10) + '...', state, error});
console.log('Session oauth:', req.session.oauth);
console.log('Session ID:', req.sessionID);
if (error) {
return res.send(`
<div style="max-width: 600px; margin: 50px auto; padding: 20px;">
<h2>Authorization Error</h2>
<p><strong>Error:</strong> ${error}</p>
<p><strong>Description:</strong> ${error_description || ''}</p>
<a href="/">← Back</a>
</div>
`);
}
if (!req.session.oauth) {
console.error('No OAuth session found');
return res.status(400).send(`
<div style="max-width: 600px; margin: 50px auto; padding: 20px;">
<h2>Session Error</h2>
<p>OAuth session not found. Please try again.</p>
<a href="/">← Back</a>
</div>
`);
}
if (req.session.oauth.state !== state) {
console.error('State mismatch:', {
expected: req.session.oauth.state,
received: state
});
return res.status(400).send(`
<div style="max-width: 600px; margin: 50px auto; padding: 20px;">
<h2>Security Error</h2>
<p>Invalid state parameter</p>
<p><small>Expected: ${req.session.oauth.state}</small></p>
<p><small>Received: ${state}</small></p>
<a href="/">← Back</a>
</div>
`);
}
try {
// Exchange code for tokens - use INTERNAL URL for server-to-server
const tokenResponse = await axios.post(
`${HYDRA_INTERNAL_URL}/oauth2/token`,
new URLSearchParams({
grant_type: 'authorization_code',
code: code,
redirect_uri: REDIRECT_URI,
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
code_verifier: req.session.oauth.verifier
}),
{
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
}
}
);
req.session.token = tokenResponse.data;
delete req.session.oauth;
res.redirect('/');
} catch (error) {
console.error('Token exchange error:', error.response?.data || error);
res.status(500).send(`
<div style="max-width: 600px; margin: 50px auto; padding: 20px;">
<h2>Token Retrieval Error</h2>
<pre>${JSON.stringify(error.response?.data || error.message, null, 2)}</pre>
<a href="/">← Back</a>
</div>
`);
}
});
// ============= Login/Consent Provider part =============
// Login handler
app.post('/auth/login', async (req, res) => {
const {email, password, challenge} = req.body;
try {
// 1. Get login flow from Kratos
const flowResp = await axios.get('http://kratos:4433/self-service/login/api');
const flowId = flowResp.data.id;
// 2. Submit login credentials to Kratos
const kratosResponse = await axios.post(
`http://kratos:4433/self-service/login?flow=${flowId}`,
{
method: 'password',
identifier: email,
password: password
},
{
headers: {'Content-Type': 'application/json'}
}
);
// If login is successful, use the entered email as subject
const userId = email;
// Save Kratos identity traits in session for consent
if (kratosResponse.data && kratosResponse.data.session && kratosResponse.data.session.identity) {
req.session.userTraits = kratosResponse.data.session.identity.traits;
} else {
req.session.userTraits = {email};
}
// Accept login in Hydra
const acceptResponse = await axios.put(
`${HYDRA_ADMIN_URL}/admin/oauth2/auth/requests/login/accept?login_challenge=${challenge}`,
{
subject: userId,
remember: true,
remember_for: 3600,
acr: '0'
}
);
return res.redirect(acceptResponse.data.redirect_to);
} catch (error) {
let errorMsg = 'Login failed';
if (error.response && error.response.data) {
if (typeof error.response.data === 'string') {
errorMsg = error.response.data;
} else if (error.response.data.error && error.response.data.error.message) {
errorMsg = error.response.data.error.message;
} else if (error.response.data.message) {
errorMsg = error.response.data.message;
} else if (error.response.data.ui && error.response.data.ui.messages && error.response.data.ui.messages.length > 0) {
errorMsg = error.response.data.ui.messages.map(m => m.text).join(' ');
}
}
console.error('Login error:', error.response?.data || error);
res.redirect(`/?login_challenge=${challenge}&error=${encodeURIComponent(errorMsg)}`);
}
});
// Login endpoint for Hydra
app.get('/login', async (req, res) => {
const {login_challenge} = req.query;
if (!login_challenge) {
// If no challenge, redirect to main
return res.redirect('/');
}
// Redirect to main with challenge
res.redirect(`/?login_challenge=${login_challenge}`);
});
// Consent endpoint - automatically grant consent
app.get('/consent', async (req, res) => {
const {consent_challenge} = req.query;
if (!consent_challenge) {
return res.status(400).send('Missing consent_challenge');
}
try {
// Get consent request
const consentRequest = await axios.get(
`${HYDRA_ADMIN_URL}/admin/oauth2/auth/requests/consent?consent_challenge=${consent_challenge}`
);
// Use user traits from session if available
const userTraits = req.session.userTraits || {
email: 'test@example.com',
name: 'Test User',
roles: ['admin', 'user']
};
// Accept consent
const acceptResponse = await axios.put(
`${HYDRA_ADMIN_URL}/admin/oauth2/auth/requests/consent/accept?consent_challenge=${consent_challenge}`,
{
grant_scope: consentRequest.data.requested_scope,
grant_access_token_audience: consentRequest.data.requested_access_token_audience,
remember: true,
remember_for: 3600,
session: {
access_token: {
email: userTraits.email,
traits: userTraits
},
id_token: {
email: userTraits.email,
name: userTraits.name,
traits: userTraits
}
}
}
);
return res.redirect(acceptResponse.data.redirect_to);
} catch (error) {
console.error('Consent error:', error.response?.data || error);
res.status(500).send('Consent error');
}
});
// ============= Additional endpoints =============
// Logout
app.post('/logout', (req, res) => {
req.session.destroy();
res.redirect('/');
});
app.listen(port, () => {
console.log(`All-in-One OAuth2 App running at http://localhost:${port}`);
console.log('This app serves as:');
console.log(' - OAuth2 Client');
console.log(' - Login Provider');
console.log(' - Consent Provider');
});Теперь создадим Dockerfile для этой страницы:
FROM node:18-alpine
WORKDIR /app
RUN npm install express axios express-session crypto
COPY . .
EXPOSE 3001
CMD ["node", "index.js"]Теперь добавим сервис в docker-compose.yml:
hydra-token-page:
build:
context: ./docker/hydra
dockerfile: Dockerfile
ports:
- "3001:3001"
networks:
- intranetТеперь у нас есть страница для получения токена доступа, которую мы можем использовать для тестирования. Запускаемdocker-compose up -d, после чего можем перейти по адресу http://127.0.1:3001 и видим страницу для получения токена.
Теперь зарегистрируем клиента:
curl -X POST http://localhost:4445/admin/clients \
-H 'Content-Type: application/json' \
-d '{
"client_id": "web",
"client_secret": "**web-secret**",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code", "id_token"],
"scope": "openid offline users:read products:read orders:read",
"redirect_uris": ["http://127.0.0.1:4455/callback"]
}'redirect_uris указывает на Kratos‑UI (порт 4455), который мы уже подняли. offline даёт refresh‑token, чтобы нелогиниться каждый час.
Теперь добавим роль пользователю, которого мы создали в Ory Kratos. Но просто добавить не можем, нам нужно модифицироватьсхему которую мы добавляли при создании Kratos. Лежит в папке docker/kratos/configs/identity.schema.json, там мыдобавляем новое свойство roles, сразу после names:
{
"roles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Список ролей пользователя, например: admin, user, moderator"
}
}Перезагружаем контейнер не нужно, применяется сразу. Дальше идем получать ID identity, его можно получить на вкладеhttp://127.0.0.1:4455/sessions. У меня это90a1e7d9-82ad-4f71-a1ab-f88ca81fd2e5 (будьте внимательны, id указывается в identity -> ID, а не первая строка). После чего отправляем запрос на добавление роли:
curl -X PATCH http://localhost:4434/admin/identities/90a1e7d9-82ad-4f71-a1ab-f88ca81fd2e5 \
-H 'Content-Type: application/json' \
-u '[
{
"op": "add",
"path": "/traits/roles/-",
"value": "admin"
}
]'Теперь получаем токен доступа, что бы протестировать. Идем на нашу страницу http://127.0.0.1:3001, вводим логин и пароль, после чего нажимаем "Login". После успешной аутентификации, вы увидите свой токен, а так же роли и scope, которые были указаны.
Проверяем что токен валидный:
curl -X POST http://127.0.0.1:4444/userinfo \
-d 'token=ВАШ_ТОКЕН'Теперь идем настраивать Apache APISIX. Для этого нам нужно создать три наших маршрута.
Показываю для одного, вам достаточно будет изменить uri и upstream.
curl -X PUT http://localhost:9180/apisix/admin/routes/users \
-H "X-API-KEY: supersecret" \
-d '{
"uri": "/users/*",
"plugins": {
"openid-connect": {
"client_id": "web",
"client_secret": "web-secret",
"discovery": "http://hydra:4444/.well-known/openid-configuration",
"bearer_only": true,
"use_jwks": true,
"token_signing_alg_values_expected": "RS256"
}
},
"proxy-rewrite": {
"regex_uri": ["^/users/?(.*)", "/$1"]
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"users:8080": 1
}
}
}'И если попытаем сделать запрос на ручку, то получим ответ:
2025/06/25 19:14:16 [warn] 63#63: *2352793 [lua] openid-connect.lua:435: introspect(): OIDC access discovery url failed : accessing discovery url (http://127.0.0.1:4444/.well-known/openid-configuration) failed: connection refused, client: 192.168.148.1, server: _, request: "GET /users/123 HTTP/1.1", host: "localhost:9080"
2025-06-25T19:14:16.273643707Z 2025/06/25 19:14:16 [error] 63#63: *2352793 [lua] openidc.lua:573: openidc_discover(): accessing discovery url (http://127.0.0.1:4444/.well-known/openid-configuration) failed: connection refused, client: 192.168.148.1, server: _, request: "GET /users/123 HTTP/1.1", host: "localhost:9080"
2025-06-25T19:14:16.273652832Z 2025/06/25 19:14:16 [error] 63#63: *2352793 [lua] openidc.lua:1006: openidc_load_jwt_and_verify_crypto(): accessing discovery url (http://127.0.0.1:4444/.well-known/openid-configuration) failed: connection refused, client: 192.168.148.1, server: _, request: "GET /users/123 HTTP/1.1", host: "localhost:9080"Проблема в том, что APISIX пытается обратиться к Hydra по адресу http://127.0.1:4444, а Hydra работает в контейнере и не доступна по этому адресу изнутри. Но если мы поменяем issuer на hydra, то мы не сможем получить токен, так как этот адрес не доступен из браузера. Самый простой способ - это добавить в файл /etc/hosts на вашей машине строку:
127.0.0.1 hydraПосле этого поменять в файле конфигурации Hydra docker/hydra/config/hydra.yml значение issuer на http://hydra:4444. И в запросе на регистрацию клиента указать redirect_uris как http://hydra:4444/callback. Так же меняем env в нашем
hydra-token-page. Затем перейти в браузер и получить новый токен.
После этого APISIX сможет корректно прокинуть запросы.
Проверка ролей
У нас все настроено, но нам нужно проверить, что у нас есть соответствующая роль.
Так как изначально статья исследовательская, ожидал что APISIX сможет это сделать, ждем когда примут PR #11824.
С помощью него можно будет сделать что-то вроде:
{
"claim_validator": {
"roles": {
"claim": "ext.traits.roles",
"match": "any",
"value": [
"orders"
]
}
}
}Потом я решил пойти в сторону добавления ролей в виде scope, например 'roles:order', но тут тоже оказалась проблема.
Hydra хранит scope в scp в токене, а APISIX умеет брать данные только в scope, если мы добавляем проверку:
{
"required_scopes": [
"roles:order"
]
}Поэтому если у вас система отдает JWT, то это рабочий вариант, но если вы используете Hydra, то тогда мы сразу отказываемся от JWT и переходим на opaque токены. Для этого нужно в конфиге Hydra изменить стратегию:
strategies:
access_token: opaqueПосле этого заходим на наш сайт, перевыпускаем токен, а дальше проверяем:
curl --request POST \
--url http://localhost:4445/oauth2/introspect \
--header "Content-Type: application/x-www-form-urlencoded" \
--user "web:web-secret" \
--data-urlencode "token=<ТВОЙ_ТОКЕН>"
Здесь уже по-человечески написано scope, а не scp. Теперь мы можем использовать APISIX для проверки ролей.
curl -X PUT http://localhost:9180/apisix/admin/routes/orders \
-H "X-API-KEY: supersecret" \
-d '{
"uri": "/users/*",
"plugins": {
"openid-connect": {
"client_id": "web",
"client_secret": "web-secret",
"discovery": "http://hydra:4444/.well-known/openid-configuration",
"bearer_only": true,
"introspection_endpoint": "http://hydra:4445/admin/oauth2/introspect",
"required_scopes": ["roles:order"]
},
"proxy-rewrite": {
"regex_uri": ["^/users/?(.*)", "/$1"]
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"users:8080": 1
}
}
}'
Теперь меняем на roles:users и видим что ручка не доступна:
Проверка прав в микросервисах
Теперь мы можем проверять уже детальные права в рамках микросервиса. Для этого мы можем использовать middleware.
Микросервис пользователя у нас будет выглядеть следующим образом:
main.go
package main
import (
"encoding/base64"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
"strings"
"github.com/gorilla/mux"
)
type UserInfo struct {
Sub string `json:"sub"`
Scope string `json:"scope"`
ClientID string `json:"client_id"`
Active bool `json:"active"`
}
func AuthMiddleware(requiredScopes ...string) mux.MiddlewareFunc {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
userInfoHeader := r.Header.Get("X-Userinfo")
if userInfoHeader == "" {
http.Error(w, "Unauthorized: Missing user info", http.StatusUnauthorized)
return
}
decoded, err := base64.StdEncoding.DecodeString(userInfoHeader)
if err != nil {
http.Error(w, "Unauthorized: Invalid user info format", http.StatusUnauthorized)
return
}
var userInfo UserInfo
if err := json.Unmarshal(decoded, &userInfo); err != nil {
http.Error(w, "Unauthorized: Invalid user info JSON", http.StatusUnauthorized)
return
}
if !userInfo.Active {
http.Error(w, "Unauthorized: Token is not active", http.StatusUnauthorized)
return
}
userScopes := strings.Split(userInfo.Scope, " ")
if !hasRequiredScopes(userScopes, requiredScopes) {
http.Error(w, "Forbidden: Insufficient permissions", http.StatusForbidden)
return
}
r.Header.Set("X-User-ID", userInfo.Sub)
r.Header.Set("X-User-Scopes", userInfo.Scope)
r.Header.Set("X-Client-ID", userInfo.ClientID)
next.ServeHTTP(w, r)
})
}
}
func hasRequiredScopes(userScopes, requiredScopes []string) bool {
scopeMap := make(map[string]bool)
for _, scope := range userScopes {
scopeMap[scope] = true
}
for _, required := range requiredScopes {
if !scopeMap[required] {
return false
}
}
return true
}
func getUserInfo(r *http.Request) (string, []string) {
userID := r.Header.Get("X-User-ID")
scopes := strings.Split(r.Header.Get("X-User-Scopes"), " ")
return userID, scopes
}
func main() {
r := mux.NewRouter()
service := os.Getenv("SERVICE_NAME")
r.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "%s service is healthy!", service)
}).Methods("GET")
r.Handle("/", AuthMiddleware("users:read")(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
userID, scopes := getUserInfo(r)
fmt.Fprintf(w, "Hello from %s service! User: %s, Scopes: %v", service, userID, scopes)
}))).Methods("GET")
r.Handle("/", AuthMiddleware("users:write")(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
userID, _ := getUserInfo(r)
fmt.Fprintf(w, "Create in %s service by user %s!", service, userID)
}))).Methods("POST")
r.Handle("/{id}", AuthMiddleware("users:read")(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
userID, _ := getUserInfo(r)
fmt.Fprintf(w, "Read %s with id %s by user %s!", service, vars["id"], userID)
}))).Methods("GET")
r.Handle("/{id}", AuthMiddleware("users:write")(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
userID, _ := getUserInfo(r)
fmt.Fprintf(w, "Update %s with id %s by user %s!", service, vars["id"], userID)
}))).Methods("PUT")
r.Handle("/{id}", AuthMiddleware("users:delete")(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
userID, _ := getUserInfo(r)
fmt.Fprintf(w, "Delete %s with id %s by user %s!", service, vars["id"], userID)
}))).Methods("DELETE")
r.Handle("/admin/stats", AuthMiddleware("admin:read", "users:read")(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
userID, scopes := getUserInfo(r)
fmt.Fprintf(w, "Admin stats for %s service. Admin: %s, Scopes: %v", service, userID, scopes)
}))).Methods("GET")
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
log.Printf("Starting %s service on port %s", service, port)
log.Fatal(http.ListenAndServe(":"+port, r))
}Теперь если отправим POST запрос на /users то получим ответ Forbidden: Insufficient permissions:
Заключение
В рамках этой статьи мы разобрали два основных подхода к реализации авторизации и аутентификации в микросервисной архитектуре. Первый подход с JWT токенами подходит для простых систем с базовыми ролями, но имеет ограничения по размеру заголовков. Второй подход с opaque токенами и интроспекцией позволяет реализовать более гибкую систему разрешений, но добавляет сетевые накладные расходы.
Мы успешно интегрировали Ory Kratos для аутентификации и Ory Hydra для авторизации, настроили Apache APISIX в качестве API Gateway и создали middleware для проверки детальных разрешений в микросервисах. Такая архитектура даёт нам:
Централизованное управление доступом через API Gateway
Гибкую систему разрешений на уровне отдельных операций
Масштабируемость за счёт микросервисной архитектуры Ory
Безопасность через использование стандартных протоколов OAuth2/OIDC
В продакшене не забудьте:
Использовать HTTPS для всех соединений
Настроить надежные пароли и секреты
Добавить мониторинг и логирование
Настроить кэширование результатов интроспекции
Продумать стратегию ротации токенов
Весь код из статьи доступен в репозитории на GitHub, где вы можете поэкспериментировать с разными настройками и адаптировать решение под свои нужды.
P.S. Пока готовил статью, так как она достаточно исследовательская, понял что проще всего вообще микросервисы держать открытыми, а авторизацию делать только на уровне API Gateway.
Сильно чаще чем статьи я пишу в своем канале в ТГ, подписывайтесь.
