Security Schemeオブジェクト

操作で使用できるセキュリティ スキームを定義します。

サポートされるスキームは、HTTP 認証、API キー (ヘッダー、Cookie パラメーター、またはクエリ パラメーターとして)、相互 TLS (クライアント証明書の使用)、OAuth2 の共通フロー (暗黙的、パスワード、クライアント資格情報、および認証コード) です。RFC6749およびOpenID Connect Discoveryで定義されています。2020 年の時点で、暗黙的フローはOAuth 2.0 Security Best Practiceによって廃止されようとしていることに注意してください。ほとんどのユースケースで推奨されるのは、PKCE を使用した認証コード付与フローです。

固定フィールド

フィールド名	タイプ	適用	説明
タイプ	string	どれでも	必須。セキュリティ方式のタイプ。有効な値は"apiKey"、"http"、"mutualTLS"、"oauth2"、"openIdConnect"です。
説明	string	どれでも	セキュリティ方式の説明。CommonMark 構文はリッチ テキスト表現に使用できます (MAY)。
名前	string	apiKey	必須。使用されるヘッダー、クエリ、または Cookie パラメーターの名前。
の	string	apiKey	必須。API キーの場所。有効な値は"query"、"cookie" 、"header"またはです。
図式	string	http	必須。RFC7235 で定義されている、Authorization ヘッダーで使用される HTTP 認可スキームの名前。使用される値は、IANA Authentication Scheme レジストリに登録される必要があります (SHOULD )。
ベアラー形式	string	http( "bearer")	ベアラー トークンの形式を識別するためのクライアントへのヒント。ベアラー トークンは通常、認可サーバーによって生成されるため、この情報は主に文書化を目的としています。
流れ	OAuth フロー オブジェクト	oauth2	必須。サポートされているフロー タイプの構成情報を含むオブジェクト。
openIdConnectUrl	string	openIdConnect	必須。OAuth2 構成値を検出するための OpenId Connect URL。これは URL の形式でなければなりません。OpenID Connect 標準では TLS の使用が必要です。

このオブジェクトは、仕様拡張機能を使用して拡張できます。

セキュリティスキームオブジェクトの例

基本認証のサンプル

{  "type": "http",  "scheme": "basic"}


type: httpscheme: basic

APIキーのサンプル

{  "type": "apiKey",  "name": "api_key",  "in": "header"}


type: apiKeyname: api_keyin: header

JWT ベアラーのサンプル

{  "type": "http",  "scheme": "bearer",  "bearerFormat": "JWT",}


type: httpscheme: bearerbearerFormat: JWT

暗黙的な OAuth2 サンプル

{  "type": "oauth2",  "flows": {    "implicit": {      "authorizationUrl": "https://example.com/api/oauth/dialog",      "scopes": {        "write:pets": "modify pets in your account",        "read:pets": "read your pets"      }    }  }}



type: oauth2flows:   implicit:    authorizationUrl: https://example.com/api/oauth/dialog    scopes:      write:pets: modify pets in your account      read:pets: read your pets