OAuth 2.0

OAuth 2.0は、APIクライアントがWebサーバー上のユーザーデータに限定的にアクセスすることを許可する認証プロトコルです。GitHub、Google、FacebookのAPIで特に使用されています。OAuthは、リソース所有者（ユーザー）が自身の認証情報を共有することなく、リソースサーバーから保護されたコンテンツを共有できるようにする*フロー*と呼ばれる認証シナリオに依存しています。この目的のために、OAuth 2.0サーバーは、クライアントアプリケーションがリソース所有者の代わりに保護されたリソースにアクセスするために使用できるアクセストークンを発行します。OAuth 2.0の詳細については、oauth.netおよびRFC 6749を参照してください。

フロー

「フロー」（「許可タイプ」とも呼ばれる）は、APIクライアントが認可サーバーからアクセストークンを取得するために実行するシナリオです。OAuth 2.0は、さまざまなタイプのAPIクライアントに適した複数のフローを提供します。

認可コード – 最も一般的なフローで、主にサーバーサイドおよびモバイルWebアプリケーションで使用されます。このフローは、ユーザーがFacebookまたはGoogleアカウントを使用してWebアプリケーションにサインアップする方法に似ています。
インプリシット – このフローでは、クライアントがアクセストークンを直接取得する必要があります。ユーザーの認証情報がクライアントコードに保存できない場合（第三者が簡単にアクセスできるため）に役立ちます。サーバーコンポーネントを含まないWeb、デスクトップ、モバイルアプリケーションに適しています。
リソース所有者パスワード認証情報（または単にパスワード） – ユーザー名とパスワードでログインする必要があります。この場合、認証情報がリクエストの一部となるため、このフローは信頼できるクライアント（例：APIプロバイダーがリリースした公式アプリケーション）にのみ適しています。
クライアントクレデンシャル – サーバー間認証を目的としたこのフローは、クライアントアプリケーションが個々のユーザーの代理としてではなく、自身の代理として動作するアプローチを記述します。ほとんどのシナリオでは、このフローはユーザーがクライアントアプリケーションに認証情報を指定できるようにする手段を提供し、それによってクライアントの制御下にあるリソースにアクセスできるようにします。

OpenAPI を使用した OAuth 2.0 の記述

OAuth 2.0を使用して保護されたAPIを記述するには、まず、グローバルな components/securitySchemes セクションに type: oauth2 を持つセキュリティスキームを追加します。次に、security キーを追加して、セキュリティをグローバルに、または個々の操作に適用します。

1
# Step 1 - define the security scheme
2
components:
3
  securitySchemes:
4
    oAuthSample:    # <---- arbitrary name
5
      type: oauth2
6
      description: This API uses OAuth 2 with the implicit grant flow. [More info](https://api.example.com/docs/auth)
7
      flows:
8
        implicit:   # <---- OAuth flow(authorizationCode, implicit, password or clientCredentials)
9
          authorizationUrl: https://api.example.com/oauth2/authorize
10
          scopes:
11
            read_pets: read your pets
12
            write_pets: modify pets in your account
13

14
# Step 2 - apply security globally...
15
security:
16
  - oAuthSample:
17
    - write_pets
18
    - read_pets
19

20
# ... or to individual operations
21
paths:
22
  /pets:
23
    patch:
24
      summary: Add a new pet
25
      security:
26
        - oAuthSample:
27
          - write_pets
28
          - read_pets
29
      ...

flows キーワードは、このOAuth 2.0スキームでサポートされている1つ以上の名前付きフローを指定します。フロー名は次のとおりです。

authorizationCode – 認可コードフロー（OpenAPI 2.0では以前は accessCode と呼ばれていました）
implicit – インプリシットフロー
password – リソース所有者パスワードフロー
clientCredentials – クライアントクレデンシャルフロー（OpenAPI 2.0では以前は application と呼ばれていました）

flows オブジェクトは複数のフローを指定できますが、各タイプにつき1つのみです。各フローには以下の情報が含まれます。

フィールド名	説明	フローに適用
フィールド名	説明	`認証コード`	`インプリシット`	`パスワード`	`クライアントクレデンシャル`
`認可URL`	このフローで使用する認証URLです。APIサーバーURLに対して相対パスにできます。	+	+	-	-
`トークンURL`	このフローで使用するトークンURLです。APIサーバーURLに対して相対パスにできます。	+	-	+	+
`refreshUrl`	オプション。リフレッシュトークンの取得に使用されるURLです。APIサーバーのURLに対して相対パスにできます。	+	+	+	+
`スコープ`	OAuth2セキュリティスキームで利用可能なスコープ。スコープ名とそれに対する短い説明のマッピング。	+	+	+	+

スコープについて

OpenAPI 3.0では、ユーザーはクライアントアプリケーションが実行したい操作に応じて異なるスコープアクセスをアカウントに付与できます。各OAuthアクセストークンには複数のスコープをタグ付けできます。スコープは、ユーザーが提供する認証情報がリソースサーバーへの必要な呼び出しを実行することを許可するかどうかを制御するアクセス権です。クライアントにすでに持っている権限以上の追加の権限を付与するものではありません。注意: 認可コードおよびインプリシットフローでは、要求されたスコープはユーザーに表示される認可フォームにリストされます。スコープを適用するには、次の2つの手順を実行する必要があります。

components/securitySchemes セクションでOAuthセキュリティ定義にサポートされているすべてのスコープを定義します。

1
components:
2
  securitySchemes:
3
    oAuthSample:
4
      type: oauth2
5
      flows:
6
        implicit:
7
          authorizationUrl: https://api.example.com/oauth2/authorize
8
          scopes:
9
            read_pets: read pets in your account
10
            write_pets: modify pets in your account

その操作の security セクションで、各操作に必要なスコープをリストアップします。

1
paths:
2
  /pets/{petId}:
3
    patch:
4
      summary: Updates a pet in the store
5
      security:
6
        - oAuthSample: [write_pets]
7
      ...

すべてのAPI操作で同じスコープが必要な場合は、代わりにAPI定義のルートレベルに security を追加できます。

1
security:
2
  - oAuthSample: [write_pets]

スコープなし

スコープはオプションであり、APIでは使用しない場合があります。この場合、スコープ定義で空のオブジェクト {} を指定し、security セクションで空のスコープリスト [] を指定します。

1
components:
2
  securitySchemes:
3
    oAuthNoScopes:
4
      type: oauth2
5
      flows:
6
        implicit:
7
          authorizationUrl: https://api.example.com/oauth2/authorize
8
          scopes: {} # <-----
9

10
security:
11
  - oAuthNoScopes: [] # <-----

相対エンドポイント URL

OpenAPI 3.0では、authorizationUrl、tokenUrl、および refreshUrl をAPIサーバーURLに対して相対的に指定できます。これらのエンドポイントが他のAPI操作と同じサーバー上にある場合に便利です。

1
servers:
2
  - url: https://api.example.com/v2
3

4
components:
5
  securitySchemes:
6
    oauth2sample:
7
      type: oauth2
8
      flows:
9
        authorizationCode:
10
          authorizationUrl: /oauth/authorize # <-----
11
          tokenUrl: /oauth/token # <-----
12
          scopes: ...

相対URLはRFC 3986に従って解決されます。上記の例では、エンドポイントは次のように解決されます。

authorizationUrl: https://api.example.com/oauth/authorize

tokenUrl: https://api.example.com/oauth/token

セキュリティスキームの例

認可コードフロー

authorization フローは authorizationUrl、tokenUrl、およびオプションの refreshUrl を使用します。以下にSlack APIの例を示します。

1
components:
2
  securitySchemes:
3
    oAuth2AuthCode:
4
      type: oauth2
5
      description: For more information, see https://api.slack.com/docs/oauth
6
      flows:
7
        authorizationCode:
8
          authorizationUrl: https://slack.com/oauth/authorize
9
          tokenUrl: https://slack.com/api/oauth.access
10
          scopes:
11
            users:read: Read user information
12
            users:write: Modify user information
13
            im:read: Read messages
14
            im:write: Write messages
15
            im:history: Access the message archive
16
            search:read: Search messages, files, and so on
17
            # etc.

インプリシットフロー

implicit フローは、認証サーバーからアクセストークンを取得するために使用される authorizationUrl を定義します。以下に例を示します。

1
components:
2
  securitySchemes:
3
    oAuth2Implicit:
4
      type: oauth2
5
      description: For more information, see https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        implicit:
8
          authorizationUrl: https://api.getbase.com/oauth2/authorize
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only

リソース所有者パスワードフロー

password フローは tokenUrl とオプションの refreshUrl を使用します。以下に例を示します。

1
components:
2
  securitySchemes:
3
    oAuth2Password:
4
      type: oauth2
5
      description: See https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        password:
8
          tokenUrl: https://api.getbase.com/oauth2/token
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only

クライアントクレデンシャルフロー

clientCredentials フローは tokenUrl とオプションの refreshUrl を使用します。以下にGetty Images APIの例を示します。

1
components:
2
  securitySchemes:
3
    oAuth2ClientCredentials:
4
      type: oauth2
5
      description: See http://developers.gettyimages.com/api/docs/v3/oauth2.html
6
      flows:
7
        clientCredentials:
8
          tokenUrl: https://api.gettyimages.com/oauth2/token/
9
          scopes: {} # Getty Images does not use scopes

複数のフロー

以下は、複数のフローをサポートする OAuth 2.0 セキュリティ定義の例です。クライアントはこれらのフローのいずれかを使用できます。

1
components:
2
  securitySchemes:
3
    oAuth2:
4
      type: oauth2
5
      description: For more information, see https://developers.getbase.com/docs/rest/articles/oauth2/requests
6
      flows:
7
        implicit:
8
          authorizationUrl: https://api.getbase.com/oauth2/authorize
9
          scopes:
10
            read: Grant read-only access to all your data except for the account and user info
11
            write: Grant write-only access to all your data except for the account and user info
12
            profile: Grant read-only access to the account and user info only
13
        password:
14
          tokenUrl: https://api.getbase.com/oauth2/token
15
          scopes:
16
            read: Grant read-only access to all your data except for the account and user info
17
            write: Grant write-only access to all your data except for the account and user info
18
            profile: Grant read-only access to the account and user info only

よくある質問

authorizationUrl と tokenUrl を API オペレーションとして追加で定義する必要がありますか？

authorizationUrl はAPIエンドポイントではなく、ユーザー入力を必要とする特殊なウェブページです。そのため、OpenAPIで記述することはできません。ただし、必要であれば tokenUrl を記述することはできます。

authorizationUrl と tokenUrl に、grant_type、client_id などのクエリ文字列パラメータを含めるべきですか？

OpenAPI Specificationではこのことについて言及されていないため、それはあなたと使用するツール次第です。

お探しのものが見つかりませんでしたか？コミュニティに尋ねる間違いを見つけましたか？お知らせください