概要

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

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

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

  1. apiKey
  2. basicAuth
  3. OAuth2

OAuth2

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

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

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

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

OAuth2:用語と役割

リソース所有者

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

リソースサーバー

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

クライアント

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

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

このフローでは、アプリケーションが OAuth2 で保護された API にアクセスしようとすると、まず、ユーザーが API Manager の OAuth2 サーバー認可エンドポイント(/oauth2/auth)にリダイレクトされます。認可リクエストを送信するための URL は次のようになります。

http://<APIM_SERVERNAME>:port/oauth2/auth?client_id=<Application Client ID>&response_type=token&scope=<list of scopes delimited by string>&state=<random string>

次に例を示します。

 

http://example.com/oauth2/auth?client_id=9a42a56d5b5546079f2f82a62612dab9&response_type=token&

state=nkj34898sdcsd123&scope=foo_read%20foo_write

 

リクエストのパラメーター

パラメーターの説明

response_type

このパラメーターは、この付与タイプのフローを識別します。値は token です。

client_id

このパラメーターは、アプリケーションを一意に識別します。値は API Manager アプリケーションで確認できます。

state

このパラメーターは、不透明な疑似乱数の文字列値です。最初の認可リクエストからコールバックまでの間、クライアントアプリケーションで状態を保持するために使用されます。これにより、クロスサイトリクエストフォージェリが防止されます。フローが開始されると、後の比較のためにスコープがローカルに格納されます。

Scope(オプション)

アクセストークンに必要なスコープのリストを指定します。複数のスコープが必要な場合は、スペースで区切って指定します。

API Manager の OAuth2 サーバーがリクエストを受け取ると、すべてのパラメーターが検証されます。パラメーターが有効で、アプリケーションの認証方式がユーザーストアの場合は、ログインページが表示されます。アプリケーションの認証方式が SAML SSO の場合は、認証のために SAML ID プロバイダーにリダイレクトされます。認証が成功すると、認可/同意のための別のページが表示されます。

そこで、アプリケーションに対して許可されるスコープのリストを選択できます。選択したリストはアクセストークンに含まれます。

アプリケーションがコールバック URL にリダイレクトされると、アプリケーションのスクリプトによって URL フラグメントからアクセストークンが抽出されます。URL フラグメントはブラウザーによって HTTP/S で送信されないので、サーバーはアクセストークンを受け取りません。コールバック URL のフラグメントには次のパラメーターが含まれます。

URL フラグメントのパラメーター

パラメーターの説明

access_token

保護された API の呼び出しに使用できる、リクエストされたアクセストークン。

token_type

リクエストされたアクセストークンの種類を指定します。現在 API Manager でサポートされているのはベアラートークンだけです。したがって、値は Bearer になります。

expires_in

アクセストークンの有効期間(秒)。アクセストークンの有効期間を設定するには、API Manager アプリケーションでアクセストークンの有効期間を変更します。

client_id

アクセストークンが発行されるアプリケーションのクライアント ID。

state

不透明な疑似乱数の文字列値。最初の認可リクエストからコールバックまでの間、クライアントアプリケーションで状態を保持するために使用されます。このパラメーターは、クロスサイトリクエストフォージェリを防止するために使用されます。

scope(オプション)

リクエストされたアクセストークンに関連付けられている付与/承認済みのスコープ。

付与タイプからアクセストークンが取得されると、保護された API が呼び出されて、API からの応答が取得されます。

クライアントアプリケーションでは、リクエストしたアクセストークンをトークン情報エンドポイントに渡すことにより、いつでもこの情報を取得できます。API Manager の OAuth2 認可サーバーはリフレッシュトークンを発行しません。発行されたアクセストークンが期限切れになると、アプリケーションで Two-Legged OAuth2 のプロセスが繰り返されます。

ログイン資格情報のタイムアウトは、API Manager の管理者ポータルで制御されます。認証がタイムアウトしたら、認証方式がユーザーストアの場合は有効な資格情報(ユーザー名とパスワード)をもう一度入力してログインします。SAML SSO IDP の場合はもう一度認可が行われます。アプリケーションが既に承認済みの場合は直接コールバック URL にリダイレクトされます。アクセストークンなどの詳細はフラグメントに含まれています。

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

OAuth2 のセキュリティは、ユーザー資格情報、OAuth2 のアクセストークンおよびクライアント資格情報を、いかに安全に送信するかにかかっています。そのため、本番環境では、すべての OAuth2 エンドポイントに HTTPS(SSL/TLS)トランスポートでアクセスすることをお勧めします。API Manager administrator の「セキュリティ設定」ページで HTTPS トランスポートを必須にすることができます。

さらに、コールバック URL でアクセストークンを受け取るため、HTTPs のコールバック URL を API Manager に登録します。アプリケーションは、フラグメントで受け取った state パラメーターの値を、最初のリクエストに格納されていた値を使用して確認します。さらに、URL フラグメントのクライアント ID が JavaScript アプリケーションコードのクライアント ID と同じであることを確認します。

アクセストークンの失効

すべてのアクセストークンに有効期限があります。有効期限が切れたアクセストークンは無効になり、自動的に失効します。アクセストークンが期限切れになると、アプリケーションは再度アクセストークンをリクエストします。期限切れになる前にアクセストークンを失効させる必要がある場合は、そのアクセストークンを失効エンドポイントに渡します。

アクセストークン失効リクエストは、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

認可コード付与タイプ(Three-Legged OAuth 2)

この付与タイプはサーバーアプリケーションに適しています。このフローでは、アクセストークンがエンドユーザーに公開されず、代わりに認可コードが発行されます。

この中間の認可コードをクライアント資格情報と共にトークンエンドポイントで使用して、アクセストークンとリフレッシュトークンを受け取ります。このフローでは、認可コードを使用してトークンへのアクセススやトークンのリフレッシュを行うためのサーバーコンポーネントもアプリケーションに必要です。コードは使用されると無効になります。

前提条件

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

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

このフローでは、まず、アプリケーションのサーバーコンポーネントによってエンドユーザーが API Manager の OAuth2 サーバー認可エンドポイント(/oauth2/auth)にリダイレクトされます。認可リクエストを送信するための URL は次のようになります。

http://<APIM_SERVERNAME>:port/oauth2/auth?client_id=<Application Client ID>&response_type=code&scope=<list of scopes delimited by string>&state=<random string>

次に例を示します。

http://example.com/oauth2/auth?client_id=9a42a56d5b5546079f2f82a62612dab9&response_type=code&

state=nkj34898sdcsd123&scope=foo_read%20foo_write

 

リクエストのパラメーター

パラメーターの説明

response_type

このパラメーターは、この付与タイプのフローを識別します。値は code です。

client_id

アプリケーションを一意に識別するアプリケーションのクライアント ID。値は API Manager アプリケーションで確認できます。

state

不透明な疑似乱数の文字列値。最初の認可リクエストからコールバックまでの間、クライアントアプリケーションで状態を保持するために使用されます。このパラメーターは、クロスサイトリクエストフォージェリを防止するために使用されます。後の比較のために状態をサーバーサイドセッションに格納します。

scope(オプション)

アクセストークンに必要なスコープのリストを指定します。複数のスコープが必要な場合は、スペースで区切って指定します。

API Manager の OAuth2 サーバーがこのリクエストを受け取ると、すべてのパラメーターが検証されます。パラメーターが有効な場合は、ログインページが表示されて、ログイン資格情報(ユーザー名とパスワード)の入力を求められます。アプリケーションの認証方式が SAML SSO の場合は、認証のために SAML ID プロバイダーにリダイレクトされます。

認証が成功すると、認可/同意のための別のページが表示されます。そこで、アプリケーションに対して許可されるスコープのリストを選択できます。選択したリストはアクセストークンに含まれます。選択したスコープが承認されると、アプリケーション(登録した URL)にリダイレクトされます。code というクエリーパラメーターとその値が、state パラメーターと共に追加されます。

リクエストの state パラメーターの値は、アプリケーションのサーバーコンポーネントによって、セッションに格納されている値を使用して確認されます。state パラメーターが確認されると、code パラメーターの値がリクエストから抽出されて、アクセストークンを取得するためにクライアント資格情報と共に使用されます。

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

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

grant_type=authorization_code&client_id=9a42a56d5b5546079f2f82a62612dab9&

client_secret=7ee85874dde4c7235b6c3afc82e3fb

渡されたクライアント資格情報と認可コードが有効な場合は、応答にアクセストークンとリフレッシュトークンが含まれます。リフレッシュトークンは、現在のアクセストークンが期限切れになった(失効した)場合に新しいアクセストークンを取得するために使用されます。JSON 応答には次のキーが含まれます。

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

{

"access_token": "95d9c3de53a9c48e629ecb6a288f6c",

"token_type": "bearer",

"expires_in": 1200,

"scope": "foo_read",

"refresh_token": "31cf059933238e866779a43237cd7ec"

}

 

JSON キー

キーの説明

access_token

保護された API の呼び出しに使用できる、リクエストされたアクセストークン。

token_type

リクエストされたアクセストークンの種類を指定します。現在 API Manager でサポートされているのはベアラートークンだけです。したがって、値は Bearer になります。

expires_in

アクセストークンの有効期間(秒)。アクセストークンの有効期間を設定するには、API Manager アプリケーションでアクセストークンの有効期間を変更します。

client_id

アクセストークンが発行されるアプリケーションのクライアント ID。

State

不透明な疑似乱数の文字列値。最初の認可リクエストからコールバックまでの間、クライアントアプリケーションで状態を保持するために使用されます。このパラメーターは、クロスサイトリクエストフォージェリを防止するために使用されます。

scope

リクエストされたアクセストークンに関連付けられている付与/承認済みのスコープ。

refresh_token

リフレッシュトークンは、有効期間の長いアクセストークンで、新しいアクセストークンのリクエストに使用されます。

クライアントアプリケーションでは、リクエストしたアクセストークンをトークン情報エンドポイントに渡すことにより、いつでもこの情報を取得できます。発行されたアクセストークンが期限切れになったら、リフレッシュトークンを使用して新しいアクセストークンを取得できます。

アクセストークンのリフレッシュ

リフレッシュトークンを使用してアクセストークンをリフレッシュする例を次に示します。フォームパラメーターまたは基本認証を使用して、クライアント資格情報をリクエストと共に渡します。

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

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

grant_type=refresh_token&refresh_token=31cf059933238e866779a43237cd7ec&scope=foo_read

リフレッシュトークンが期限切れになったら(失効したら)、Three-Legged OAuth2 のプロセスを繰り返します。認証がタイムアウトしたら、認証方式がユーザーストアの場合は有効な資格情報(ユーザー名とパスワード)をもう一度入力してログインします。SAML SSO IDP の場合はもう一度認可が行われます。アプリケーションが既に承認済みの場合は、中間の認可コードと状態を使用して直ちにコールバック URL にリダイレクトされます。

アクセス/リフレッシュトークンの失効

発行されたアクセストークンには、それぞれ有効期限が関連付けられています。有効期限が切れたアクセストークンは無効になり、自動的に失効します。アクセストークンが期限切れになると、アプリケーションは新しいアクセストークンを取得します。期限切れになる前にアクセストークンを失効させる必要がある場合は、そのアクセストークンを失効エンドポイントに渡します。

アクセストークン失効リクエストは、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

失効エンドポイントでは、リフレッシュトークンの失効もサポートされています。token パラメーターでリフレッシュトークンを渡して、token_type_hint パラメーターの値を refresh_token に設定します。

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

OAuth2 のセキュリティは、ユーザー資格情報、OAuth2 のアクセストークンおよびクライアント資格情報を、いかに安全に送信するかにかかっています。そのため、本番環境では、すべての OAuth2 エンドポイントに HTTPS(SSL/TLS)トランスポートでアクセスすることをお勧めします。API Manager administrator の「セキュリティ設定」ページで HTTPS トランスポートを必須にすることができます。さらに、コールバック URL で認可コードを受け取るため、HTTPS のコールバック URL を API Manager アプリケーションに登録します。サーバーアプリケーションは、リクエストで受け取った state パラメーターの値を、セッションに格納されている値を使用して確認します。アクセストークン、リフレッシュトークンおよびクライアント資格情報は、サーバーアプリケーションによって安全なデータベースに保管されます。

リソース所有者/パスワード付与タイプ

この付与タイプを使用すると、アプリケーション独自のログインページを使用できます。パスワード付与タイプは、アプリケーションを完全に信頼できる場合に使用します。信頼されているモバイルアプリケーションやデスクトップアプリケーションに適しています。この付与タイプでは、アクセストークンのリクエストでユーザーとのやり取りが必要です。

前提条件

アプリケーションを API Manager に登録する必要があります。OAuth2 を使用して保護された API が少なくとも 1 つアプリケーションでサブスクライブされている必要があります。登録したアプリケーションに、このフロー/付与タイプに必要なクライアント ID が含まれている必要があります。この付与タイプが機能するためには、サブスクライブされている、種類がユーザーストアの API がすべて同じユーザーストアを使用して設定されていることが重要です。

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

このフローでは、ユーザーがインストールされているアプリケーションにアクセスすると、まず、そのアプリケーションのログインフォームが表示されます。ユーザーがログイン資格情報(ユーザー名とパスワード)を入力すると、アプリケーションから API Manager の OAuth2 サーバーに認可リクエストが送信されます。

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

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

リクエストのパラメーター

パラメーターの説明

grant_type

リクエストする付与タイプを指定します。このフローを使用する場合、値は password です。

client_id

アプリケーションを一意に識別するアプリケーションのクライアント ID。値は API Manager アプリケーションで確認できます。

user name

エンドユーザーが入力したユーザー名。

password

エンドユーザーが入力したパスワード。

scope(オプション)

アクセストークンに必要なスコープのリストを指定します。複数のスコープが必要な場合は、スペースで区切って指定します。

POST /oauth2/token HTTP/1.1

Host: example.com

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

grant_type=password&username=maxwell&password=sdcoio2380&client_id= 95d9c3de53a9c48e629ecb6a288f6c&scope=foo_read%20foo_write

API Manager サーバーは、受信したリクエストを検証して、クライアント ID が有効かどうか、パスワード付与タイプの使用を許可されているかどうかを確認します。さらに、アプリケーションの認証方式がユーザーストアかどうかを確認して、指定されたユーザー名とパスワードをユーザーストアに対して認証します。認証が成功したら、リクエストされたスコープを検証します。

リクエストされたスコープが空でない場合は、各スコープについて、グループ/ロールのメンバーシップが必要かどうかを確認します。スコープで指定されているロールにユーザーが含まれていれば、そのスコープは承認されます。承認されたスコープを含むアクセストークンが、リフレッシュトークンと共に、応答の一部として返されます。JSON 応答には次のキーが含まれます。

JSON キー

キーの説明

access_token

保護された API の呼び出しに使用できる、リクエストされたアクセストークン。

token_type

リクエストされたアクセストークンの種類を指定します。現在 API Manager でサポートされているのはベアラートークンだけです。したがって、値は Bearer になります。

expires_in

アクセストークンの有効期間(秒)。アクセストークンの有効期間を設定するには、API Manager でアクセストークンの有効期間を変更します。

scope

リクエストされたアクセストークンに関連付けられている付与/承認済みのスコープ。

refresh_token

リフレッシュトークンは、有効期間の長いアクセストークンで、新しいアクセストークンのリクエストに使用されます。

 

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

{                                                             

"access_token": "95d9c3de53a9c48e629ecb6a288f6c",

"token_type": "bearer",

"expires_in": 2800,

"scope":"foo_read foo_write",                                                 

"refresh_token": "31cf059933238e866779a43237cd7ec"

}

クライアントアプリケーションでは、リクエストしたアクセストークンをトークン情報エンドポイントに渡すことにより、いつでもこの情報を取得できます。発行されたアクセストークンが期限切れになったら、リフレッシュトークンを使用して新しいアクセストークンを取得できます。

アクセストークンのリフレッシュ

リフレッシュトークンを使用してアクセストークンをリフレッシュする例を次に示します。

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

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

grant_type=refresh_token&refresh_token=31cf059933238e866779a43237cd7ec&scope=foo_read

リフレッシュトークンが期限切れになると(失効すると)、アプリケーションから資格情報の入力を求められます。フロー全体を繰り返す必要があります。

アクセス/リフレッシュトークンの失効

発行されたアクセストークンには、それぞれ有効期限が関連付けられています。有効期限が切れたアクセストークンは無効になり、自動的に失効します。アクセストークンが期限切れになると、アプリケーションは新しいアクセストークンを取得します。期限切れになる前にアクセストークンを失効させる必要がある場合は、そのアクセストークンを失効エンドポイントに渡します。

アクセストークン失効リクエストは、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

失効エンドポイントでは、リフレッシュトークンの失効もサポートされています。token パラメーターでリフレッシュトークンを渡して、token_type_hint パラメーターの値を refresh_token に設定します。

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

OAuth2 のセキュリティは、ユーザー資格情報、OAuth2 のアクセストークンおよびクライアント資格情報を、いかに安全に送信するかにかかっています。そのため、本番環境では、すべての OAuth2 エンドポイントに HTTPS(SSL/TLS)トランスポートでアクセスすることをお勧めします。クライアントアプリケーションでは、ユーザー資格情報はどこにも格納されず、アクセストークンは安全に格納されます。デスクトップアプリケーションの場合は、安全なデータベースを使用します。Android モバイルアプリケーションの場合は、SharedPreferences API を使用してアクセストークンとリフレッシュトークンを格納します。iOS の場合は、キーチェーンにトークンを格納します。

OAuth2 で保護された API の呼び出し

いずれかの付与タイプからアクセストークンを取得したら、それを使用して OAuth2 で保護された API を呼び出すことができます。認可ヘッダーのフォーマットは次のようになります。

Authorization: Bearer <OAuth2 Access Token>

認可ヘッダーでアクセストークンを渡す方法を次に示します。

GET example.com/sampleapi/v1.0/examples HTTP/1.1

Host: example.com

Authorization: Bearer 7ee85874dde4c7235b6c3afc82e3fb

現在 API Manager で発行されるのはベアラートークンだけです。アクセストークンは API Manager によって検証されます。トークンが有効な場合は、さらに、その保護された API を呼び出すためのスコープがあるかどうかが確認されます。

両方の条件が満たされている場合は、バックエンドが呼び出され、応答が取得されて、クライアントに返されます。

API キー認証

API キーは、API を使用するための簡単な認証形式である不透明トークンです。API キーを取得するには、サブスクライバーとしてアプリケーションを作成します。

API キーを使用して保護された API の使用

リクエストでは、次のいずれかの方法で API キーを API Manager に渡すことができます。

  • ヘッダー:api_key ヘッダーを使用して、API キーを API ランタイムに渡すことができます。
  • クエリーパラメーター:api_key クエリーパラメーターを使用して、API キーを渡すことができます。
  • フォームパラメーター:api_key フォームパラメーターを使用して、API キーを渡すことができます。

API キーを使用して保護された API を使用する場合、API ランタイムによってヘッダー内の API キーがチェックされます。キーが見つからない場合、次にクエリーパラメーターがチェックされます。クエリーパラメーターでもキーが見つからない場合は、フォーム(ポスト)パラメーターがチェックされます。

抽出された API キーが有効であれば、API Manager は、この API キーが承認されているかどうかをチェックします。キーが承認されている場合、API Manager はこのサブスクリプションの SLA プランを取得し、これを使用して頻度制限とスロットルを適用します。

API キーの再生成

API キーを再生成すると、アプリケーションの古いキーは無効になります。アプリケーションは、API キーを使用する際に新しいキーを使用します。

基本認証

基本認証は、API を使用する際にリクエストでユーザー名とパスワードを渡すことによってユーザーを認証する、最も簡単な認証方式です。API Manager では、基本認証スキームを使用して API を保護できます。

パブリッシャーは、認証に使用するユーザーストアを設定できます。また、API リソースがロールで設定されたスコープで保護されている場合、API Manager は API 呼び出しの使用時にロールも承認します。

API Manager でアプリケーションを作成し、基本認証を使用して保護された API をサブスクライブします。

HTTP 基本認証では、ユーザーのユーザー名とパスワードが連結され、base64 でエンコードされて、Authorization HTTP ヘッダーで渡されます。次に例を示します。

Authorization: BASIC Base64 (username:password)

例:Authorization: Basic dm9yZGVsOnZvcmRlbA==

しかし、ユーザー名やパスワードを渡すだけでは、API を使用するアプリケーションは識別されません。したがって、アプリケーションの一意の識別子(クライアント ID)をリクエストと共に送信します。

基本認証を使用して保護された API を使用する例を次に示します。

GET example.com/sampleapi/v1.0/examples HTTP/1.1

Host: example.com

Authorization: Basic dm9yZGVsOnZvcmRlbA==

clientid: 3ffb313f16856a4d6b1feecd2e50b950

API Manager は、基本認証を使用して保護された API に対するリクエストを受け取ると、アプリケーション ID を探します。リクエストで受け取ったアプリケーション ID(クライアント ID)が有効であり、承認済みの場合、API Manager はリクエストに含まれる資格情報を認証します。

認証が成功すると、API Manager は、リクエストされた現在の API が適切なスコープと承認済みのロールで保護されているかどうかをチェックします。該当する場合、API Manager はユーザーロールを取得し、この API を使用するために必要なすべてのロールが現在のユーザーに割り当てられているかどうかをチェックします。ロールの承認が成功すると、API Manager は頻度制限とスロットルを適用するためにこのサブスクリプションの SLA プランを取得します。頻度制限も許可されると、アプリケーションからの応答を取得するためにリクエストが転送されます。

本作品は Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License によってライセンス許可を受けています。  Twitter™ および Facebook の投稿には、Creative Commons の規約内容は適用されません。

法律上の注意   |   プライバシーポリシー