API Manager の認証タイプ

概要

API Manager で、API キーを使用して API およびアプリケーションを認証できます。API Manager は、API キーを生成し、API キーベースの認証を API に追加できるようにします。

API キーを使用した検証は、API の作成中に実施できるセキュリティのタイプです。アプリケーションは API キーを使用し、API Manager は API キーがリソースに対して承認された状態かどうかをチェックします。

API Manager は、3 種類の API 認証タイプを使用します。

apiKey
basicAuth
OAuth2

OAuth2

従来のクライアント／サーバーアプリケーションでは、クライアントが保護されたリソース／Web ページを要求したときに、サーバーがクライアントを認証する必要があります。クライアントが資格情報をサーバーに渡すと、認証が行われます。認証結果に基づいて、クライアントは保護されたリソースへのアクセス権を取得します。この方法は、組織またはエンティティがクライアントアプリケーションとサーバーアプリケーションの両方を管理している環境では問題なく機能します。

今日の組織では、API メカニズムを使用してデータを共有するオープンなコラボレーティブプラットフォームアーキテクチャが採用されています。API メカニズムを使用すると、すべての開発者が（社内の開発者も顧客も）、サービス所有者を介さずにすばやくサービスを利用できます。このフレームワークにより、ユーザーは、マッシュアップ、モバイルおよびデスクトップのクライアントアプリケーション、その他のサードパーティサービスを構築できます。

多くの場合、サービスは認証／アクセス制御を必要とする API の機密データにアクセスする必要があります。ユーザー名とパスワードによる認証は、一般的な認証方式の 1 つです。ただし、パスワードをサードパーティアプリケーションで入力する場合、多くのデメリットがあります。サードパーティアプリケーションでパスワードを入力するには、ユーザーの信頼が必要です。また、ユーザビリティの観点から、パスワードが変更されるまでアプリケーションを取り消すことはできません。同様に、パスワードが変更された場合、アプリケーションの動作が不安定になります。

OAuth2 は、パスワードアンチパターンに関連するこの種のリスクに対処します。OAuth2 は、パスワードを入力せずに、ユーザーの代わりにアプリケーションに認可を委任するための標準です。ユーザーパスワードの代わりに、有効期間が制限されたアクセストークンをアプリケーションに提供します。アプリケーションの種類によって、アクセストークンの取得方法が異なります。これらのアクセストークンは付与タイプと呼ばれます。OAuth 2.0 について詳しくは、IETF の OAuth 2.0 の仕様を参照してください。

OAuth2：用語と役割

リソース所有者

保護された API へのアクセスを許可できるエンティティ。エンドユーザーがリソース所有者になることもあります。リソース所有者は、サードパーティクライアント／アプリケーションに認可を委任します。この委任により、アプリケーションはリソース所有者の代わりに API にアクセスできます。

リソースサーバー

API をホストするサーバー。保護された API に対するリクエストを受け入れ、アクセストークンを使用してリクエストに応答します。API Manager は、アクセストークンを検証し、保護された API のアクセス制御を行うリソースサーバーとして機能します。

Client

リソース所有者の代わりに認可を取得して、保護されたリソースのリクエストを行うアプリケーション。「クライアント」という用語は、特定の実装の特性を意味しているわけではありません（例えば、アプリケーションが実行されているのが、サーバー、デスクトップ、その他のデバイスのどれであるかは問いません）。API Manager アプリケーションは OAuth2 クライアントです。

認可サーバー

リソース所有者の認証と認可の取得が成功した後に、クライアントにアクセストークンを発行するサーバー。API Manager は、認可サーバーの役割も果たします。

アクセストークン

アクセストークンは、保護された API へのアクセスに使用される資格情報です。アクセストークンは、クライアントに発行された認可を表す文字列です。この文字列は、クライアントに対して不透明です。トークンは、リソース所有者によって許可され、リソースサーバーと認可サーバーによって適用されるアクセスのスコープと期間を表します。現在、API Manager では、不透明トークンであるベアラーアクセストークンをサポートしています。

リフレッシュトークン

リフレッシュトークンは、アクセストークンの取得に使用される資格情報です。リフレッシュトークンは、認可サーバーによってクライアントに発行されます。クライアントは、現在のトークンが無効または期限切れになった場合にリフレッシュトークンを取得します。

認可コード

認可コード付与フローで取得される不透明コード。有効期間が限られたアクセストークンとリフレッシュトークンを取得する際に使用できます。コードが使用され、無効になると、アクセストークンの取得に使用することはできません。

スコープ

スコープは、保護されたリソースに関連付けられたアクセス許可です。パブリッシャーが OAuth2 を使用してリソースを保護する場合、スコープも指定するには、そのスコープが関連付けられたアクセストークンが必要です。

クライアント ID

OAuth2 認可を使用するすべてのアプリケーションに一意の識別子があります。

クライアントシークレット

クライアントシークレットは、クライアント資格情報フローと認可コードフローでアクセストークンを取得する際に使用されます。

API Manager は、認証プロバイダー、スコープのロールベースの認可フレームワーク、ログイン Web ページとトークン管理コンポーネントなど、OAuth2 を完全にサポートします。API Manager は、認可サーバーとリソースサーバーの両方の役割を果たします。認証プロバイダーは、LDAP、データベース、SAML を使用したフェデレーション認証との統合をサポートしています。

OAuth2 エンドポイント

API Manager の OAuth2 プロバイダーは、アクセストークンの取得と管理に使用する次のエンドポイントを提供します。

認可エンドポイント

http(s)://servername:serverport/oauth2/auth：認可エンドポイントは、エンドユーザーがログインし、認証付与をアプリケーションにプロビジョニングすることに同意する場所です。

トークンエンドポイント

http(s)://servername:serverport/oauth2/token：クライアントが認証付与またはリフレッシュトークンを提示してアクセストークンを取得する際に使用されるエンドポイントです。

リダイレクトエンドポイント

ユーザーは、認可エンドポイントとやり取りした後に、アプリケーションにリダイレクトされます。API Manager で作成されたアプリケーションで、リダイレクト（またはコールバック）URL を指定します。現在、API Manager では、アプリケーションでの複数のリダイレクト URL の登録はサポートしていません。

トークン情報エンドポイント

http(s)://servername:serverport/oauth2/tokeninfo：トークン情報エンドポイントは、アクセストークンに関する情報を提供します。エンドポイントの応答には、作成時刻、有効期限、ログインしたユーザーのアプリケーション ID（client_id）、スコープなどの情報が含まれます。

次の 2 とおりの方法で、アクセストークンをトークン情報エンドポイントに渡すことができます。

1. access_token クエリパラメーターを使用

2. 認可ヘッダーを使用

access_token クエリパラメーターを含む簡単な HTTP GET リクエストの例を次に示します。

http(s)://example.com/oauth2/tokeninfo?access_token=3ffb313f16856a4d6b1feecd2e50b950

認可ヘッダーを使用した例を次に示します。

GET example.com/oauth2/token HTTP/1.1

Host: example.com

Authorization: Bearer 3ffb313f16856a4d6b1feecd2e50b950

トークン失効エンドポイント

http(s)://servername:serverport/oauth2/revoke：このエンドポイントを使用して、アクセストークンまたはリフレッシュトークンを失効させることができます。アクセストークンまたはリフレッシュトークンを失効させると、それらのトークンは無効になります。

OAuth2 Self Service

http(s)://servername:serverport/oauth2/self/<Logon Identifier>：OAuth2 サーバー認証プロバイダーがユーザーストア（LDAP またはデータベース）の場合、エンドユーザーは承認済みのスコープと共に承認済みのアプリケーションのリストを表示できます。また、エンドユーザーは任意のアプリケーションアクセスを失効させることもできます。このポータルをセットアップするには、ユーザーストアでログイン識別子を設定します。

アプリケーションの登録

アクセストークンや認可コードを取得するには、アプリケーションを API Manager に登録します。アプリケーションは、API Manager の認可サーバーによって識別されます。アプリケーションを API Manager に登録すると、次のキーのペアが提供されます。

クライアント ID：クライアント ID は公開 ID です。
クライアントシークレット：クライアントシークレットは秘密 ID です。

デプロイしたアプリケーションがトークンにアクセスできるように、アプリケーションのコールバック URL（リダイレクト URL）を API Manager に登録します。OAuth2 の付与タイプを使用するには、使用する付与タイプに関係なく、OAuth2 を使用して保護された API を少なくとも 1 つサブスクライブしている必要があります。

付与タイプ

付与とは、OAuth2 で保護された API にアクセスするためのアクセストークンの取得方法です。OAuth2 には、アプリケーションの種類（サーバー、ブラウザー、モバイルなど）に基づく各種のシナリオに対応する複数の付与タイプが用意されています。

クライアント資格情報付与タイプ

クライアント資格情報は、OAuth 2.0 の 4 つの付与タイプの中で最もシンプルな付与タイプです。この付与タイプは、クライアントタイプが Confidential のアプリケーション（クライアント資格情報を安全に格納できるアプリケーション）で API を使用する場合に使用できます。

前提条件

アプリケーションを API Manager に登録する必要があります。アプリケーションが、OAuth2 を使用して保護された API を少なくとも 1 つサブスクライブしている必要があります。

アクセストークンのリクエスト

このフロー／付与タイプでは、次の詳細を含むリクエストがトークンエンドポイントに送信されます。HTTP POST を使用して HTTPs リクエストが送信されます。content-type は「application/x-www-form-urlencoded」です。

http(s)://servername:serverport/oauth2/token

リクエストのパラメーター	パラメーターの説明
grant_type	リクエストする付与タイプを指定します。このフローを使用する場合、値は client_credentials です。
client_id	アプリケーションを一意に識別する ID。値は API Manager アプリケーションで確認できます。
client_secret	API Manager でアプリケーションに登録されているクライアント資格情報を指定します。
scope（オプション）	アクセストークンに必要なスコープのリストを指定します。複数のスコープが必要な場合は、スペースで区切って指定します。

スコープを含むアクセストークンをリクエストする HTTP リクエストの例を次に示します。

POST example.com/oauth2/token HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=625bc9f6-3bf6-4b6d-94ba-e97cf07a22de&client_secret=625bc123-3bf6-4b6d-94ba-e97cf07a22de&scope=sample_read%20sample_write

クライアント ID とクライアントシークレットの送信には認可ヘッダーを使用します。スコープと共にクライアント資格情報を認可ヘッダーで渡してアクセストークンをリクエストする HTTP リクエストの例を次に示します。

Authorization: Basic Base64 (clientId:clientSecret)

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=sample_read%20sample_write

アクセストークンの応答

アクセストークンのリクエストが成功すると、JSON 形式の応答が送信されます。JSON には次のキーが含まれます。

応答のパラメーター	応答のパラメーターの説明
access_token	保護された API の呼び出しに使用できるアクセストークン。
token_type	リクエストされたアクセストークンの種類を指定します。現在 API Manager でサポートされているのはベアラートークンだけです。
expires_in	アクセストークンの有効期間（秒）。アクセストークンの有効期間を設定するには、API Manager アプリケーションでアクセストークンの有効期間を変更します。
scope（オプション）	リクエストされたアクセストークンに関連付けられている付与／承認済みのスコープ。

JSON 応答の例を次に示します。

{

"access_token": "7ee85874dde4c7235b6c3afc82e3fb",

"token_type": "bearer",

"expires_in": 1200,

"scope": " sample_read sample_write"

}

クライアントアプリケーションでは、リクエストしたアクセストークンをトークン情報エンドポイントに渡すことにより、いつでもこの情報を取得できます。このフローでは直接クライアント認証を使用しているため、エンドポイントの応答にユーザー情報は含まれません。

アクセストークンの失効

すべてのアクセストークンに有効期限があります。有効期限が切れたアクセストークンは無効になり、自動的に失効します。トークンが期限切れになると、アプリケーションで新しいトークンがリクエストされて付与されます。クライアント資格情報フロー／付与タイプでは、リフレッシュトークンは付与されません。期限切れになる前にアクセストークンを失効させる必要がある場合は、そのアクセストークンを失効エンドポイントに渡します。クライアント資格情報を使用するアクセストークンでは、トークン失効リクエストでもクライアント資格情報を渡す必要があります。

アクセストークン失効リクエストは、API Manager の OAuth2 失効エンドポイントに送信されます。クライアント資格情報フローを使用して発行されたアクセストークンを失効させる HTTP リクエストの例を次に示します。

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token&client_id=625bc9f6-3bf6-4b6d-94ba-e97cf07a22de&client_secret=625bc123-3bf6-4b6d-94ba-e97cf07a22de

クライアントシークレットの再生成

ポータルにログインしてクライアントシークレットを生成すると、クライアントシークレットへの不正アクセスを防ぐことができます。

クライアントシークレットが再生成されると、古いクライアントシークレットは無効になります。新しいクライアントシークレットを使用して新しいアクセストークンをリクエストしてください。

セキュリティに関する注意事項

OAuth2 のセキュリティは、OAuth2 のアクセストークンとクライアント資格情報をいかに安全に送信するかにかかっています。そのため、本番環境では、すべての OAuth2 エンドポイントに HTTPS（SSL／TLS）トランスポートでアクセスします。

API Manager administrator の「セキュリティ設定」ページにある「HTTPS 必須」を選択すると、すべての OAuth2 エンドポイントで HTTP 経由のリクエストが受け入れられなくなります。クライアントシークレットは、他人に知られないように、安全なデータベースに保管します。

アプリケーションは非公開にします。そうしないと、アプリケーションのソースコードを逆コンパイル／分析されて、資格情報を攻略される可能性があります。このフローは、ストレージのセキュリティが保証されているサーバーサイドアプリケーションで使用してください。

クライアント資格情報付与と API キーセキュリティの違い

クライアント資格情報では、API の呼び出しにアクセストークンが使用されます。一方、API キーセキュリティでは、API キーを使用して API を検証できます。セキュリティ管理のレイヤーが追加されるため、クライアントアプリケーションを変更することなく簡単にアクセストークンを失効させることができます。

暗黙的／トークン付与タイプ（Two-Legged OAuth2）

暗黙的／トークン付与は、ブラウザベースのリダイレクトフローの一種です。ユーザー資格情報を格納できない、サーバーサイドコンポーネントを持たない純粋な JavaScript（クライアントサイド）中心のアプリケーションやモバイルアプリケーションに適しています。

例えば、Angular／Ember を使用して作成され、Ajax 呼び出しを使用して JavaScript から直接 API を呼び出す純粋な JavaScript アプリケーションなどで使用できます。この付与タイプ／フローではエンドユーザーとのやり取りが必要です。

前提条件

アプリケーションを API Manager に登録する必要があります。アプリケーションが、OAuth2 を使用して保護された API を少なくとも 1 つサブスクライブしている必要があります。API Manager でコールバック URL（リダイレクト URL）を指定する必要があります（認可リクエストが完了すると、登録した URL にリダイレクトされます）。登録したアプリケーションに、このフロー／付与タイプに必要なクライアント ID が含まれている必要があります。