Identity & Access Proxy

Identity & Access Proxy (IAP) — центральный компонент контроля доступа в Spirit IAM, берет на себя все функции по контролю доступа. Построен на базе Ory Oathkeeper.

Основные функции

• Может защищать любые ресурсы, доступные по протоколу HTTP(S).
• Производит аутентификацию входящих HTTP-запросов.
• Производит авторизацию HTTP-запросов путем выполнения политик.
• Может работать как обратный прокси-сервер перед API или веб-сервером в режиме Policy Enforcement Point (PEP).
• Может быть подключен к API-шлюзам (Kong, Nginx, Envoy, AWS API Gateway и т.д.) в режиме Policy Decision Point (PDP).
• Использует PBAC (ABAC) модель доступа и поддерживает MtRBAC — модель доступа.

Режимы работы

Policy Enforcement Point (PEP)

@startuml
actor Client
participant "Sidecar Proxy (PEP)" as sidecar
participant "Service" as service

Client --> sidecar : Request (JWT)
activate Client
activate sidecar

sidecar -> sidecar : Verify policy

alt Access allowed
    sidecar --> service : Forward request
    activate service
    service --> sidecar : Response
    deactivate service
    sidecar --> Client : 200 OK
else Access denied
    sidecar --> Client : 403 Forbidden
end

deactivate sidecar
deactivate Client
@enduml

Policy Decision Point (PDP)

@startuml
actor Client
participant "API Gateway (PEP)" as gateway
participant "PDP" as pdp
participant "Application" as app

Client --> gateway : Request (JWT, API Key)
activate Client
activate gateway

gateway --> pdp : Is access allowed?
activate pdp

pdp --> gateway : Permit / Deny
deactivate pdp

alt Permit
    gateway --> app : Forward request
    activate app
    app --> gateway : Response
    deactivate app
    gateway --> Client : 200 OK
else Deny
    gateway --> Client : 403 Forbidden
end

deactivate gateway
deactivate Client
@enduml

Пайплайн обработки запроса

Пайплайн обработки запроса — это последовательность этапов, через которые проходит каждый HTTP-запрос в Identity & Access Proxy (IAP).

IAP построен на базе Ory Oathkeeper Zero Trust Proxy. Архитектура прокси следует оригинальной архитектуре Oathkeeper с некоторыми отличиями в реализации отдельных компонентов.

Внутри IAP запрос проходит через следующие этапы в строгом порядке:

1. Обработка правил доступа (Access Rule Matching)
       ↓
2. Аутентификация (Authentication)
       ↓
3. Авторизация (Authorization)
       ↓
4. Мутация (Mutation)
       ↓
5. Обработка ошибок (Error Handling)

Каждый этап может либо пропустить запрос дальше, либо прервать обработку с соответствующей ошибкой.

Этап 1. Обработка правил доступа (Access Rule Matching)

На этом этапе IAP определяет, какое правило доступа (Access Rule) применить к входящему запросу.

Правила доступа содержат:

• match — условия сопоставления (URL, HTTP-методы);
• authenticators — список аутентификаторов для проверки;
• authorizer — авторизатор для проверки прав доступа;
• mutators — мутаторы для трансформации запроса;
• errors — обработчики ошибок.

Важно!

На данный момент в правилах доступа поддерживаются только glob паттерны для сопоставления URL, в отличие от upstream-версии Oathkeeper, которая поддерживает regex.

Пример правила доступа:

- id: "my-rule"
  match:
    url: "https://my-app.com/api/<.*>"
    methods: ["GET", "POST"]
  authenticators:
    - handler: spirit_iam
  authorizer:
    handler: opa_builtin
    config:
      policy: my_policy.rego
  mutators:
    - handler: header
      config:
        headers:
          X-User: "{{ print .Subject }}"
  errors:
    - handler: json

Этап 2. Аутентификация (Authentication)

Аутентификатор отвечает за проверку учетных данных запроса и извлечение информации о субъекте. Подробнее см. в статье Аутентификация.

Аутентификатор исследует HTTP-запрос (например, заголовок Authorization или cookies) и выполняет бизнес-логику, которая возвращает:

• true (аутентификация успешна) или false (аутентификация не удалась);
• subject — идентификатор субъекта (пользователь, сервис, система).

Конфигурация аутентификатора

Каждый аутентификатор имеет два ключа:

• handler (string, required) — определяет тип аутентификатора — например, spirit_iam, jwt, cookie_session.
• config (object, optional) — конфигурация аутентификатора. Ключи конфигурации зависят от типа аутентификатора.

{
  "authenticators": [
    {
      "handler": "spirit_iam",
      "config": {
        "spirit_iam_base_url": "https://<spirit-iam-host>"
      }
    }
  ]
}

Приоритет аутентификаторов

В правиле доступа можно определить несколько аутентификаторов:

{
  "authenticators": [
    { "handler": "spirit_iam" },
    { "handler": "jwt" },
    { "handler": "cookie_session" }
  ]
}

Важно

Первый аутентификатор, способный обработать предоставленные учетные данные, будет использован. Остальные аутентификаторы игнорируются.

Если аутентификатор может обработать учетные данные, но они невалидны, другие аутентификаторы также игнорируются и запрос отклоняется.

Типы аутентификаторов

1. Основные аутентификаторы Spirit IAM — поддерживает все методы аутентификации Spirit IAM:

   • Session cookie;
   • Opaque access tokens;
   • JWT-токены, включая системные JWT;
   • Делегированные токены (token exchange).
   Примечание

   Единый аутентификатор Spirit IAM работает со всеми токенами и всеми поддерживаемыми методами аутентификации.

2. Специальные аутентификаторы:

   • noop — пропускает все запросы без проверки учетных данных. Используйте для публичных ресурсов, health-check эндпоинтов или тестирования конфигурации IAP.
   • unauthorized — отклоняет все запросы с ошибкой 401 Unauthorized. Полезен для временного блокирования доступа к ресурсам или явного запрета доступа к определенным путям.
   • anonymous — проверяет наличие заголовка Authorization и устанавливает subject в anonymous (или другое заданное значение), если заголовок отсутствует. Подходит для сценариев с частично открытым доступом, где требуется отслеживание анонимных пользователей.

Этап 3. Авторизация (Authorization)

Авторизатор отвечает за проверку прав субъекта на выполнение запрошенного действия над ресурсом. Подробнее см. в статье Авторизация.

Авторизатор получает информацию о субъекте от аутентификатора и определяет, имеет ли субъект необходимые разрешения для доступа к ресурсу.

Примечание

В отличие от аутентификаторов авторизатор может быть только один на правило доступа (соотношение 1:1).

Типы авторизаторов

В Spirit IAM поддерживается только один основной авторизатор opa_builtin — встроенный движок на базе Open Policy Agent (OPA). Другие авторизаторы из Ory Oathkeeper не поддерживаются.

Для написания политик и правил доступа используется язык Rego. Подробнее см. в статье Разработка ABAC политик авторизации. Политики доступа хранятся рядом с инстансом IAP в виде файлов и подставляются как часть конфигурации.

Важно

Сейчас IAP использует OPA v0.35.0.

Этап 4. Мутация (Mutation)

Мутатор трансформирует учетные данные из входящего запроса в формат, понятный вашему backend-приложению.

Например, заголовок Authorization: basic может быть трансформирован в X-User: <subject-id>. Это позволяет писать backend-приложения, которые не зависят от типа исходных учетных данных.

Типы мутаторов

Поддерживаются стандартные мутаторы Ory Oathkeeper:

• noop — не трансформирует запрос, пропускает заголовки как есть.
• id_token — трансформирует информацию об аутентификации в подписанный JWT (OpenID Connect ID Token).
• header — добавляет заголовки к запросу, например, X-User: <subject-id>.
• cookie — добавляет cookies к запросу.
• hydrator — получает дополнительные данные из внешних API для использования другими мутаторами.

Внимание!

Если вы обогащаете запрос данными, для которых в сервисе дополнительно выполняете контроль доступа, вы используете систему неправильно. Размазывание ответственности между IAP и защищенным приложением может привести к непредвиденным проблемам и снижает прозрачность системы.

Этап 5. Обработка ошибок (Error Handling)

Обработчик ошибок выполняет логику после того, как аутентификация или авторизация не удалась.

Обработчик ошибок может быть сконфигурирован для выполнения при определенных условиях. Например, можно настроить JSON-ответ для клиентов, ожидающих application/json, или HTTP Redirect для браузеров.

Условия выполнения (Error Matching)

Обработчики ошибок могут быть настроены на выполнение при определенных условиях:

• error — тип ошибки (unauthorized, forbidden, internal_server_error и другие).
• request.header.accept — ожидаемый MIME-тип клиента.
• request.header.content_type — тип контента запроса.
• request.remote_ip — IP-адрес клиента, поддерживает CIDR-нотацию.

Типы обработчиков ошибок

1. Поддерживаются стандартные обработчики ошибок Ory Oathkeeper:

   • json — возвращает ответ в формате application/json (включен по умолчанию).
   • redirect — возвращает HTTP 302/301 redirect с заголовком Location.
   • www_authenticate — возвращает HTTP 401 с заголовком WWW-Authenticate.

2. Fallback-обработчик. Можно использовать, если ни один из обработчиков не подошел по условиям.

Схема процесса обработки запроса

Подробная схема процесса обработки запроса

@startuml
actor User as user
box "Service Deployment"
    participant "Oathkeeper \nsidecar" as gw
    participant "Service" as os
end box

participant "Spirit IAM" as iam

user -> gw: API request /service/entity

activate gw

gw -> gw: run authenticators

opt Custom authenticator
  gw -> iam: get authN context
  activate iam
  iam --> gw: authN context
  deactivate iam

  opt Bad credentials
      gw --> user: 401 authN error
  end opt

  gw -> gw: render {input} for OPA
end opt

opt No matching authenticator
    gw --> user: 401 authN error
end opt

gw -> gw: run authorizers


opt opa authorizer
  gw -> gw: OPA run policies
opt NO allow policies
    gw --> user: 403 access denied
end opt
  gw -> gw: allowed request
end opt

gw -> os: user request

note over os
  В общем случае защищаемый сервис
  не должен реализовывать логику
  аутентификации/авторизации.
  Все дошедшие до него запросы
  считаются авторизованными.
end note

activate os
os --> gw: response
deactivate os
gw -> user: response
deactivate gw
@enduml