АдминистрированиеПоставщики удостоверений

Использование WIF с Okta

Федерация идентификаторов сервисных приложений Okta с Claude API с помощью Workload Identity Federation.

Okta может выступать в роли поставщика идентификации рабочих нагрузок, выдавая токены доступа OIDC сервисному приложению (service application) через грант OAuth 2.0 client_credentials. Ваша рабочая нагрузка аутентифицируется в Okta (обычно с помощью private_key_jwt, поэтому общий секрет не хранится), получает подписанный «JSON Web Token» (веб-токен JSON), или JWT, и обменивает этот JWT у Anthropic на краткосрочный токен доступа.

URL издателя сервера авторизации Okta имеет вид https://<your-domain>.okta.com/oauth2/<auth-server-id>. Если вы используете встроенный сервер по умолчанию, путь будет /oauth2/default.

Существует множество способов настройки Okta и аутентификации в ней, которые выходят за рамки данной документации. Убедитесь, что ваши механизмы настройки и аутентификации соответствуют рекомендациям и практикам безопасности вашей компании.

Предварительные требования

Знакомство с концепциями WIF: сервисные учётные записи, издатели федерации и правила федерации.
Организация Okta с включённым API Access Management (требуется для пользовательских серверов авторизации).
Разрешение на создание сервисных учётных записей, издателей федерации и правил федерации в Claude Console для вашей организации Anthropic.
Рабочая нагрузка, которая может запрашивать токен у конечной точки Okta /v1/token и обращаться к api.anthropic.com.

Настройка Okta

В общих чертах вам необходимо:

Создать сервисное приложение Okta.
Настроить сервер авторизации по умолчанию (или создать новый пользовательский сервер авторизации) с аудиторией, областью (scope), политикой доступа и любыми пользовательскими утверждениями (claims), по которым вы хотите выполнять сопоставление.

Точная навигация зависит от конфигурации вашей организации Okta и версии консоли администратора. Следующие пронумерованные шаги описывают один из распространённых путей:

Создайте интеграцию сервисного приложения. В Okta Admin Console создайте новую интеграцию приложения типа API Services (OIDC, machine-to-machine). Запишите сгенерированный Client ID.
Настройте аутентификацию клиента. Для настройки без ключей выберите Public key / Private key (private_key_jwt) и зарегистрируйте публичный JWK вашей рабочей нагрузки. В качестве альтернативы используйте секрет клиента, если ваша среда может безопасно его хранить. Для следующего примера вам может потребоваться отключить требование DPoP для приложения; убедитесь, что ваша производственная конфигурация соответствует требованиям безопасности вашей организации.
Задайте аудиторию. На вашем пользовательском сервере авторизации установите аудиторию https://api.anthropic.com, чтобы выдаваемые токены доступа содержали это утверждение aud. Anthropic проверяет aud на соответствие этому фиксированному значению.
Предоставьте область. На вашем пользовательском сервере авторизации убедитесь, что существует хотя бы одна область, которую сервисному приложению разрешено запрашивать (например, anthropic.access). Okta отклоняет запросы client_credentials, не включающие предоставленную область.
Создайте политику доступа. На вашем пользовательском сервере авторизации создайте политику доступа хотя бы с одним правилом, разрешающим вашему сервисному приложению запрашивать область, предоставленную на шаге 4.
(Необязательно) Добавьте пользовательские утверждения. Если вы хотите выполнять сопоставление по чему-либо, кроме идентификатора клиента, добавьте утверждение в токен доступа на вкладке Claims вашего сервера авторизации.

Для сервисного приложения, использующего client_credentials, Okta устанавливает утверждение sub выданного токена доступа равным Client ID приложения, а iss — равным URL издателя сервера авторизации.

Настройка Anthropic

В Claude Console откройте Settings → Workload identity, нажмите Connect workload и выберите Custom OIDC. Мастер проведёт вас через регистрацию издателя, создание сервисной учётной записи и создание правила федерации.

Мастер создаёт эти ресурсы за вас. Используйте следующие значения независимо от того, вводите ли вы их в мастере или отправляете в Admin API:

Издатель федерации: используйте URL вашего пользовательского сервера авторизации Okta и режим обнаружения (discovery). Anthropic считывает документ обнаружения Okta .well-known/openid-configuration и получает JWKS по адресу jwks_uri, который в нём указан.

{
  "name": "okta-prod",
  "issuer_url": "https://acme.okta.com/oauth2/aus1a2b3c4d5e6f7g8h9",
  "jwks": { "type": "discovery" }
}

Правило федерации: выполняйте сопоставление по утверждению Okta sub, которое является Client ID сервисного приложения. Если вы определили пользовательские утверждения в Okta, вы можете вместо этого выполнять сопоставление по ним с помощью карты claims или CEL-выражения condition.

{
  "name": "okta-pipeline",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "0oa1b2c3d4e5f6g7h8i9",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Получение токена и вызов Claude API

В отличие от платформенно-нативных поставщиков (AWS, Google Cloud, Kubernetes), которые делают токен доступным внутри среды выполнения рабочей нагрузки (через проецируемый файл или локальную конечную точку метаданных), Okta этого не делает. Ваша рабочая нагрузка должна вызвать конечную точку токенов Okta, чтобы получить JWT, а затем передать этот JWT в Anthropic SDK в качестве токена идентификации.

import os
import httpx2
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx2.post(
        f"{os.environ['OKTA_ISSUER']}/v1/token",
        data={
            "grant_type": "client_credentials",
            "scope": "anthropic.access",
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            # Сформируйте JWT client_assertion по RFC 7523, подписанный закрытым ключом вашего приложения Okta
            "client_assertion": build_signed_client_assertion(),
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_okta_token,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

На каждой вкладке SDK показан паттерн с вызываемым объектом: Anthropic SDK повторно вызывает ваш поставщик токена идентификации всякий раз, когда срок действия токена доступа Anthropic приближается к истечению, поэтому ваш загрузчик токенов Okta должен возвращать свежий токен при каждом вызове, а не кэшировать один токен бессрочно. CLI ant повторно считывает ANTHROPIC_IDENTITY_TOKEN_FILE при каждом обмене, поэтому для долго работающих оболочек обновляйте этот файл по таймеру.

Проверка настройки

Успешный обмен возвращает access_token, начинающийся с sk-ant-oat01-, и значение expires_in в секундах. Если обмен завершается неудачей с непрозрачным ответом 401 authentication_error (сообщение Authentication failed), проверьте причину отказа на странице истории аутентификации и обратитесь к разделу Устранение неполадок при неудачном обмене; наиболее распространённая причина на стороне Okta — несоответствие issuer_url (он должен включать путь /oauth2/<auth-server-id>; сервер авторизации организации Okta использовать нельзя).

Ограничение области действия правила

Ограничьте блок match правила самой узкой областью, подходящей для вашего сценария использования:

Закрепите точный Client ID: установите subject_prefix равным полному Client ID сервисного приложения без завершающего *.
Закрепите аудиторию: сопоставляйте значение audience, настроенное на сервере авторизации, чтобы токены, выпущенные для другой аудитории, отклонялись.
Сопоставляйте по пользовательским утверждениям: для более детального ограничения добавьте утверждения на вкладке Claims сервера авторизации и сопоставляйте их с помощью карты claims правила или CEL-выражения condition.
Используйте одно правило на сервисное приложение: создавайте отдельное правило федерации для каждого сервисного приложения, а не используйте одно правило для нескольких приложений.

Следующие шаги

Ознакомьтесь со справочником WIF, чтобы узнать полный порядок разрешения учётных данных и конфигурацию профилей.
См. справочник WIF, чтобы выполнять сопоставление по пользовательским утверждениям Okta с помощью CEL-выражений.

Предварительные требования

Настройка Okta

Настройка Anthropic

Получение токена и вызов Claude API

Проверка настройки

Ограничение области действия правила

Следующие шаги