メインコンテンツまでスキップ

認証 API リファレンス(SaaS)

AGENTIC STAR SaaS版の OIDC エンドポイント仕様、JWT クレーム構造、スコープ、エラーコードのリファレンスです。

エンドポイント一覧

SaaS
メソッドエンドポイント説明
GET/realms/federation/.well-known/openid-configurationOpenID Connect Discovery エンドポイント
GET/federation/auth/v1/authorizeAuthorization Code フローのユーザー認可エンドポイント
POST/federation/auth/v1/tokenトークン取得エンドポイント(AC / CC / Refresh Token フロー対応)
GET / POST/federation/auth/v1/userinfoユーザー情報取得エンドポイント(GET / POST 両対応)
GET/federation/auth/v1/jwks公開鍵セット(JWKS)エンドポイント
POST/federation/auth/v1/revokeトークン失効エンドポイント

ホスト: https://auth.fd.agenticstar.tm.softbank.jp

Issuer: https://auth.fd.agenticstar.tm.softbank.jp/realms/federation

Discovery

GET/realms/federation/.well-known/openid-configuration

クライアントが必要なエンドポイント URL やサーバー情報を取得します。

互換用エイリアスとして、RFC 8414 (OAuth 2.0 Authorization Server Metadata) パスでも同一のレスポンスを返します:

GET /realms/federation/.well-known/oauth-authorization-server

リクエスト例

curl
curl https://auth.fd.agenticstar.tm.softbank.jp/realms/federation/.well-known/openid-configuration

レスポンス例

JSON
{
"issuer": "https://auth.fd.agenticstar.tm.softbank.jp/realms/federation",
"authorization_endpoint": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/authorize",
"token_endpoint": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token",
"userinfo_endpoint": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/userinfo",
"jwks_uri": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/jwks",
"revocation_endpoint": "https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke",
"grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"],
"response_types_supported": ["code"],
"response_modes_supported": ["query"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256"],
"token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
"code_challenge_methods_supported": ["S256"]
}

Authorization Code フロー

GET/federation/auth/v1/authorize

ユーザーが認証してアプリケーションを認可し、Authorization Code を取得します。ウェブブラウザで直接アクセスしてください。

クエリパラメータ

パラメータ必須説明
client_idstring必須クライアントID
redirect_uristring必須認可後にリダイレクトするURI(事前登録が必要)
response_typestring必須code を指定してください
statestring推奨CSRF 対策用。クライアントが生成した予測不可能な値。指定した場合はレスポンスで返却されるため、リクエスト時の値と一致を検証してください
noncestringID Token への nonce クレーム挿入用(推奨)

リクエスト例

curl
https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/authorize?\
client_id=my-client&\
redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&\
response_type=code&\
state=abc123xyz&\
nonce=xyz789abc

レスポンス(302 Redirect)

ユーザーが認可に成功した場合、以下の形式でリダイレクトされます:

https://app.example.com/callback?\
code=AUTH_CODE&\
state=abc123xyz

エラーレスポンス

エラーが発生した場合、以下の形式でリダイレクトされます:

https://app.example.com/callback?\
error=invalid_scope&\
error_description=...&\
state=abc123xyz
エラーコード説明
invalid_request必須パラメータが不足している、または形式が不正
unauthorized_clientクライアントが認可フローを使用する権限がない
unsupported_response_typeresponse_typecode 以外の値(このサービスは code のみサポート)
access_deniedクライアントが無効化されている、またはアクセスが拒否された
invalid_scopeリクエストされたスコープが無効または不足
server_errorサーバー側のエラー

Token エンドポイント

POST/federation/auth/v1/token

Authorization Code フローまたは Client Credentials フローでアクセストークンを取得します。

リクエストヘッダー

ヘッダー必須説明
Content-Type必須application/x-www-form-urlencoded

Authorization Code フロー

リクエストボディ

パラメータ必須説明
grant_typestring必須authorization_code を指定
codestring必須Authorization Code エンドポイントから取得した認可コード
redirect_uristring必須Authorization Code 要求時に指定した redirect_uri と同一値
client_idstring必須クライアントID
client_secretstring必須クライアントシークレット(バックエンド間通信で安全に送信してください)

リクエスト例

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE" \
-d "redirect_uri=https://app.example.com/callback" \
-d "client_id=my-client" \
-d "client_secret=my-secret"

Client Credentials フロー

リクエストボディ

パラメータ必須説明
grant_typestring必須client_credentials を指定
client_idstring必須クライアントID
client_secretstring必須クライアントシークレット

リクエスト例

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=my-m2m-client" \
-d "client_secret=my-secret"

レスポンスフィールド(200 OK)

フィールド説明
access_tokenstringJWT 形式のアクセストークン
id_tokenstringJWT 形式の ID Token
expires_innumberアクセストークンの有効期限(秒)
refresh_expires_innumberリフレッシュトークンの有効期限(秒)。AC フローのみ
refresh_tokenstringリフレッシュトークン(トークン更新に使用)。AC フローのみ
token_typestring"Bearer"
scopestring付与されたスコープ(スペース区切り)

レスポンス例(Authorization Code フロー)

JSON
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"id_token": "eyJhbGciOiJSUzI1NiIs...",
"expires_in": 3600,
"refresh_expires_in": 86400,
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"scope": "openid chat:exec chat:history chat:file"
}

レスポンス例(Client Credentials フロー)

JSON
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"id_token": "eyJhbGciOiJSUzI1NiIs...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "openid users:read logs:read"
}
Client Credentials フローのレスポンス

Client Credentials フローではリフレッシュトークンは発行されません。refresh_token および refresh_expires_in フィールドはレスポンスに含まれません。

エラーレスポンス

ステータスエラーコード説明
400invalid_request必須パラメータが不足、または形式が不正
401invalid_clientクライアント認証に失敗(ID / Secret が不正)
400invalid_grantAuthorization Code が無効、または有効期限切れ
400unauthorized_clientクライアントの利用条件を満たさない(例: 利用者のテナントが無効化されている、またはクライアントが「非公開」状態で developer ロールが必要)
400invalid_scopeリクエストされたスコープが無効
502bad_gateway認証基盤(KC)との通信に失敗

Refresh Token

POST/federation/auth/v1/token

Refresh Token を使用してアクセストークンを更新します。grant_type=refresh_token を指定します。

リクエストボディ

パラメータ必須説明
grant_typestring必須refresh_token を指定
refresh_tokenstring必須Token エンドポイントから取得した Refresh Token
client_idstring必須クライアントID
client_secretstring必須クライアントシークレット

リクエスト例

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=REFRESH_TOKEN" \
-d "client_id=my-client" \
-d "client_secret=my-secret"

レスポンスフィールド(200 OK)

Token エンドポイントと同じ構造のレスポンスが返されます。Token エンドポイント — レスポンスフィールドを参照してください。

レスポンス例

JSON
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"id_token": "eyJhbGciOiJSUzI1NiIs...",
"expires_in": 3600,
"refresh_expires_in": 86400,
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"scope": "openid chat:exec chat:history chat:file"
}

エラーレスポンス

ステータスエラーコード説明
400invalid_request必須パラメータが不足、または形式が不正
401invalid_clientクライアント認証に失敗(ID / Secret が不正)
400invalid_grantRefresh Token が無効、または有効期限切れ
502bad_gateway認証基盤(KC)との通信に失敗

UserInfo

GET/federation/auth/v1/userinfo

有効なアクセストークンを使用してユーザー情報を取得します。テナント経由の認証の場合、OIDC 標準クレームに加えて idp ブロックに IdP のユーザー情報が含まれます。

OIDC Core 1.0 §5.3 に準拠し、GETPOST のどちらでも同一のレスポンスを返します。POST を使う場合も Authorization: Bearer <access_token> ヘッダーで認証してください。

リクエストヘッダー

ヘッダー必須説明
Authorization必須Bearer <access_token>

リクエスト例

curl
curl https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/userinfo \
-H "Authorization: Bearer <access_token>"

レスポンスフィールド(200 OK)

フィールド説明
substringユーザー ID(OIDC 標準)
idpobjectIdP から取得したユーザー情報(テナント経由の場合のみ)
idp.substringIdP 側のユーザー ID
idp.namestringユーザー名
idp.preferred_usernamestringユーザー名(メールアドレス)
idp.emailstringメールアドレス
idp.email_verifiedbooleanメールアドレスが検証済みか
idp.organizationobject所属組織(id と label を含む)
idp.jobobject役職(id と label を含む)
idp.biostring自己紹介

レスポンス例

JSON
{
"sub": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"idp": {
"sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "yamada_taro",
"preferred_username": "taro.yamada@example.com",
"email": "taro.yamada@example.com",
"email_verified": true,
"organization": {
"id": "org-001",
"label": "Example Corp."
},
"job": {
"id": "job-001",
"label": "Engineer"
},
"bio": "Software engineer"
}
}

エラーレスポンス

ステータスエラーコード説明
401invalid_tokenトークンが無効または有効期限切れ
500server_error認証基盤(KC)または IdP の設定エラー
502bad_gatewayIdP からのユーザー情報取得に失敗

JWKS

GET/federation/auth/v1/jwks

JWT 署名検証用の公開鍵セット(JWKS)を取得します。ID Token や Access Token の署名検証に使用してください。

リクエスト例

curl
curl https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/jwks

レスポンスフィールド(200 OK)

フィールド説明
keysarrayJWK(JSON Web Key)オブジェクトの配列
keys[].ktystring鍵タイプ(例: "RSA")
keys[].kidstring鍵 ID。JWT ヘッダーの kid と照合して検証に使用する鍵を特定
keys[].usestring鍵の用途。"sig"(署名検証)
keys[].algstringアルゴリズム(例: "RS256")
keys[].nstringRSA 公開鍵のモジュラス(Base64url エンコード)
keys[].estringRSA 公開鍵の指数(Base64url エンコード)

レスポンス例

JSON
{
"keys": [
{
"kty": "RSA",
"kid": "key-id-1",
"use": "sig",
"alg": "RS256",
"n": "modulus...",
"e": "AQAB"
}
]
}

Revoke

POST/federation/auth/v1/revoke

アクセストークンや Refresh Token を失効させます。

リクエストヘッダー

ヘッダー必須説明
Content-Type必須application/x-www-form-urlencoded

リクエストボディ

パラメータ必須説明
tokenstring必須失効させるトークン(Access Token または Refresh Token)
client_idstring必須クライアントID
client_secretstring必須クライアントシークレット

リクエスト例

curl
curl -X POST https://auth.fd.agenticstar.tm.softbank.jp/federation/auth/v1/revoke \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "token=ACCESS_TOKEN" \
-d "client_id=my-client" \
-d "client_secret=my-secret"

レスポンスフィールド(200 OK)

成功時は 200 OK(空のレスポンスボディ)が返されます。トークンが既に無効であっても 200 OK が返されます(RFC 7009 準拠)。

エラーレスポンス

ステータスエラーコード説明
400invalid_request必須パラメータが不足、または形式が不正
401invalid_clientクライアント認証に失敗(ID / Secret が不正)
502bad_gateway認証基盤(KC)との通信に失敗

JWT 仕様

ID Token および Access Token は JWT 形式で発行されます。JWT は署名済み(署名アルゴリズム: RS256)で、header.payload.signature の3部から構成されています。

JWT 構造

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLWlk....signature_part
JSON
{
"alg": "RS256",
"typ": "JWT",
"kid": "key-id-1"
}

Payload(クレーム)

以下のセクションで詳細なクレーム一覧を参照してください。

クレーム一覧

標準クレーム

AC(Authorization Code)フローと CC(Client Credentials)フローの両方に含まれるクレームです。

クレーム説明
substringサブジェクト ID。認証基盤内でユーザーまたはサービスアカウントを一意に識別する UUID
issstringIssuer。トークン発行元(https://auth.fd.agenticstar.tm.softbank.jp/realms/federation)
expnumber有効期限(Unix タイムスタンプ)
iatnumber発行日時(Unix タイムスタンプ)
jtistringJWT ID。トークンを一意に識別する ID
typstringトークン種別("Bearer")
azpstringAuthorized Party。トークンを要求したクライアント ID
scopestring付与されたスコープ(スペース区切り)
preferred_usernamestringユーザー名(CC フローのみ、service-account-<client-id>@federation.invalid 形式)

AC フロー固有クレーム

Authorization Code フローで発行されたトークンにのみ含まれるクレームです。

クレーム説明
audstringAudience。固定値 "broker"(認証基盤内部の対象識別子)
sidstringSession ID。認証セッションの識別子
auth_timenumberユーザー認証が完了した日時(Unix タイムスタンプ)
allowed-originsstring[]許可された Origin(CORS 用途)

テナント情報(tenant.*

テナント(企業 / SaaS)に関する情報です。AC / CC の両方で、Access Token および ID Token にネスト構造で含まれます。

クレーム説明トークン
tenant.idstringテナント IDAT / IDT
tenant.typestringenterprise または saasAT / IDT
tenant.endpointstringテナントのエンドポイント URLAT / IDT

IdP プロフィール(idp.*

IdP(企業認証基盤)から取得したユーザー情報です。AC フローではログインしたユーザーの情報がネスト構造で含まれます。CC フローでは idp.* は含まれません。

クレーム説明トークン
idp.substringIdP ユーザー IDAT / IDT
idp.preferred_usernamestringIdP ユーザー名(メールアドレス)AT / IDT
idp.display_namestring表示名IDT
idp.emailstringメールアドレスIDT
idp.organizationstring所属組織AT / IDT
idp.jobstring役職AT / IDT
idp.biostring自己紹介AT / IDT

ロール

クレーム説明
realm_access.rolesstring[]Realm ロール。AC ではユーザーに付与されたロール(例: user, admin, developer)、CC では ["M2M"] 固定
resource_access.<client>.rolesstring[]クライアント固有ロール(AC フローのみ付与される場合あり)

Access Token Payload 例(Authorization Code フロー)

JSON
{
"exp": 1745049600,
"iat": 1745048100,
"jti": "onrtac:abc12345-6789-4def-8abc-0123456789ab",
"iss": "https://auth.fd.agenticstar.tm.softbank.jp/realms/federation",
"aud": "broker",
"sub": "11111111-2222-3333-4444-555555555555",
"typ": "Bearer",
"azp": "my-client",
"sid": "99999999-8888-7777-6666-555555555555",
"allowed-origins": ["http://localhost:4000"],
"realm_access": {
"roles": ["admin", "developer", "user"]
},
"resource_access": {
"broker": { "roles": ["read-token"] }
},
"scope": "openid mcp:all chat:file chat:history email a2a:all profile chat:exec",
"auth_time": 1745048090,
"tenant": {
"id": "enterprise-a",
"type": "enterprise",
"endpoint": "https://enterprise-a.example.com"
},
"idp": {
"sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"organization": "Enterprise A Division",
"bio": "Software developer",
"preferred_username": "user@enterprise-a.com",
"job": "Engineer"
}
}

Access Token Payload 例(Client Credentials フロー)

JSON
{
"exp": 1745049600,
"iat": 1745048100,
"jti": "trrtcc:abc12345-6789-4def-8abc-0123456789ab",
"iss": "https://auth.fd.agenticstar.tm.softbank.jp/realms/federation",
"sub": "22222222-3333-4444-5555-666666666666",
"typ": "Bearer",
"azp": "my-cc-client",
"realm_access": {
"roles": ["M2M"]
},
"scope": "openid sharedmemory:query users:manage master:manage logs:read users:read",
"preferred_username": "service-account-my-cc-client@federation.invalid",
"tenant": {
"id": "enterprise-a",
"type": "enterprise",
"endpoint": "https://enterprise-a.example.com"
}
}
注記
  • AC フローは aud"broker" 固定)、sidauth_timeallowed-origins を含みますが、CC フローには含まれません。
  • AC フローの realm_access.roles は Console で割り当てたユーザーロール、CC フローは "M2M" 固定です。

スコープ

スコープ一覧

スコープ説明
chat:execチャットの開始・停止、ストリーミング応答の受信、成果物の取得
chat:history会話一覧・メッセージ履歴の取得(アクティブ / アーカイブ)、会話の削除・タイトル更新・アーカイブ済み会話の復元、メッセージ検索
chat:fileチャットで使用するファイルのアップロード・取得・削除
mcp:allMCP(Model Context Protocol)でエージェントに接続
a2a:allA2A(Agent-to-Agent)プロトコルでエージェントに接続
sharedmemory:query共有メモリの検索
users:readユーザー情報の読み取り(一覧・詳細)
users:manageユーザーの管理操作(承認・承認取り消し・削除・ロール変更)。読み取り権限を含む
logs:readログの閲覧(監査ログ・LLMログ・アクセスログ)
master:manageマスターデータの管理(部署・職種の作成・更新・削除)

各スコープの詳細や選択の指針については、認証ガイド — スコープを参照してください。

スコープ制御の仕組み

Console でクライアントにスコープを割り当てることで、トークンに含まれるスコープが決定されます。ユーザーのロールで許可されたスコープのみがトークンに付与されます。

エラーコード

OAuth 2.0 / OIDC エラー

エラーコード説明対応方法
invalid_request必須パラメータが不足、または形式が不正リクエストパラメータを確認してください
unauthorized_clientクライアントに権限がない、またはクライアント ID が不正クライアント ID と設定を確認してください
invalid_clientクライアント認証に失敗(ID / Secret が不正)クライアント ID とシークレットを確認してください
invalid_grantAuthorization Code が無効、有効期限切れ、または既に使用済みAuthorization Code を再取得してください
invalid_scopeリクエストされたスコープが無効、または未割り当てConsole でクライアントにスコープを割り当ててください
server_error認証基盤との通信エラーなど、サーバー側のエラーしばらく待ってから再度お試しください。問題が続く場合はサポートに連絡してください
invalid_tokenトークンが無効または有効期限切れ新しいトークンを取得してください

HTTP ステータスコード

ステータス説明
200 OKリクエストが成功
302 Foundリダイレクト(Authorization エンドポイント)
400 Bad Requestリクエストが不正
401 Unauthorized認証に失敗、またはトークンが無効
403 Forbiddenリクエストが禁止されている
500 Internal Server Errorサーバー内部エラー
502 Bad Gateway認証基盤との通信に失敗