API の概要


Idm API

Identity Manager (IdM) GE API 仕様は、認証とユーザの既存の標準に準拠し、アクセス情報を提供します。

この仕様は、開発技術を持つサービス・コンシューマーとクラウドプロバイダーを対象としています。前者については、このドキュメントでは、Identity Management Service API との相互運用方法の完全な仕様を提供しています。後者の場合、この仕様は、記述された機能を提供するためにクライアント・アプリケーション開発者に提供されるインタフェースを示します。この情報を使用するには、最初にGeneric Enabler サービスの一般的な知識が必要です。

API ユーザは次の知識が必要です :

  • RESTful Web サービス
  • HTTP/1.1
  • JSON および/または、XML データのシリアル化形式

ユーザは API を使用して次の操作を実行できます :

  • 認証
  • アプリケーションの管理

FIWARE Lab インスタンス (OAuth2) の使用

ユーザ・アカウントの登録

FIWARE IdM の使用を開始するには、まず自分のアカウントを登録する必要があります。ユーザ&プログラマ・ガイド に、どのように行うか記載されています。

アプリケーションの登録

次のステップは、独自のアプリケーションを登録することです。Callback URL 属性は、OAuth2 認証で使用される必須パラメータです。IdM は、OAuth2 で使用される Client IDClient Secret を提供します。ユーザ&プログラマ・ガイド に、どのように行うか記載されています。

OAuth2 認証

FIWARE IdM は、RFC 6749 に記述されている OAuth2 標準に準拠しており、そこに定義されている4つの許可タイプすべてをサポートしています。

Authorization Basic ヘッダは、標準に従ったFIWARE IdM によって提供される Client IDClient Secret 資格情報で構成されています。文字列は次のようになります :

base64(client_id:client_secret)

redirect_uri パラメータは、アプリケーション登録で指定された Callback URL 属性と一致する必要があります。

認証コードの付与

認証コードは、クライアント(登録アプリケーション)とリソース所有者(ユーザ)との間の仲介として認証サーバ (IdM) を使用して取得されます。リソース所有者から直接、認証をリクエストするのではなく、クライアントはリソース・オーナを RFC2616 で定義されたユーザ・エージェントを介して、認証サーバに指示し、リソースオーナーは認証コードを使用してクライアントに返送します。

認証リクエスト

GET /oauth2/authorize?response_type=code&client_id=1&state=xyz
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcallback_url HTTP/1.1
Host: idm-portal

response_type 属性は必須であり、code に設定する必要があります。client_id 属性は、アプリケーションの登録時に FIWAREのIdM が提供するものです。redirect_uri 属性は、アプリケーション登録内のIDMに提供する Callback URL 属性に一致しなければなりません。state は、必要に応じたオプションで、アプリケーションの内部使用のためのものです。

認証レスポンス

HTTP/1.1 302 Found
Location: https://client.example.com/callback_url?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

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

POST /oauth2/token HTTP/1.1
Host: idm-portal
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcallback_url

アクセス・トークンのレスポンス

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
}

暗黙の付与 (Implicit Grant)

暗黙の付与は、JavaScript などのスクリプト言語を使用してブラウザに実装されたクライアント用に最適化された単純化された認証コード・フローです。暗黙のフローでは、クライアントに認証コードを発行するのではなく、リソース所有者の許可の結果として、クライアントに直接アクセス・トークンが発行されます。中間の資格情報(認証コードなど)が発行されず、後でアクセス・トークンを取得するために使用されるので、認可タイプは暗黙的です。

認証リクエスト

GET /oauth2/authorize?response_type=token&client_id=1&state=xyz
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcallback_url HTTP/1.1
Host: idm-portal

response_type 属性は必須であり、token に設定する必要があります。

client_id 属性は、アプリケーションの登録時に FIWARE の IdM が提供するものです。

redirect_uri 属性は、アプリケーション登録内のIDMに提供する Callback URL 属性に一致しなければなりません。

state は、必要に応じたオプションで、アプリケーションの内部使用のためのものです。

アクセス・トークンのレスポンス

HTTP/1.1 302 Found
Location: https://client.example.com/callback_url?token=SplxlOBeZQQYbYS6WxSbIA&token_type=Bearer&expires_in=3600&state=xyz&

リソース・オーナーのパスワード資格情報の付与

リソース・オーナーのパスワード資格情報 (つまり、ユーザ名とパスワード) は、アクセス・トークンを取得するための認可付与として直接使用できます。

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

POST /oauth2/token HTTP/1.1
Host: idm-portal
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=demo&password=123

アクセス・トークンのレスポンス

Authorization Code Grant を参照してください

Authorization Code Grant を参照してください

クライアントは、最初に取得したリフレッシュ・トークンを使用して新しいトークンをリクエストすることができます。ただし、クライアント資格情報の付与タイプを除く別の付与タイプ(グラント・タイプ)を使用します。

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

POST /oauth2/token HTTP/1.1
Host: idm-portal
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

アクセス・トークンのレスポンス

承認コードの許可を参照してください

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

クライアントは、クライアント資格情報のみを使用してアクセス・トークンをリクエストできます。

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

POST /oauth2/token HTTP/1.1
Host: idm-portal
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

アクセス・トークンのレスポンス

Authorization Code Grantを参照してください

ユーザ情報とロールの取得

警告

クライアント資格情報の付与を使用してトークンを取得した場合、この付与(グラント)の性質のために、"許可ユーザ" というものは存在しないことに注意してください。このエンド・ポイントを引き続きトークンの検証に使用できますが、JSON (トークンが有効な場合) は空になります。

リクエスト :

GET /user?access_token=2YotnFZFEjr1zCsicMWpAA

レスポンス例 :

    {
      id: 1,
      displayName: "Demo user",
      email: "demo@fiware.org",
      roles: [
        {
          id: 15,
          name: "Manager"
        },
        {
          id: 7
          name: "Ticket manager"
        }
      ],
      organizations: [
        {
           id: 12,
           name: "Universidad Politecnica de Madrid",
           roles: [
             {
               id: 14,
               name: "Admin"
             }
          ]
        }
      ]
    }