トークン

ユーザーが正常に認証されると、アプリケーションは App ID からトークンを受け取ります。このサービスでは、アクセス・トークン、ID トークン、リフレッシュ・トークンと呼ばれる、主に 3 種類のトークンを使用して認証プロセスを完了する。

アクセス・トークン

アクセス・トークンとは許可を表すものであり、App ID で設定された許可フィルターで保護されているバックエンド・リソースとの通信を可能にします。このトークンは JavaScript Object Signing and Encryption (JOSE) 仕様に準拠しています。トークンは JSON Web トークンとしてフォーマットされ、 RS256 アルゴリズムを使用する JSON Web 鍵で署名されます。

トークンの例:

Header:
{
   "alg": "RS256",
   "typ": "JWT",
   "kid": "appId-39a37f57-a227-4bfe-a044-93b6e6050a61-2018-08-02T11:57:43.401",
   "ver": 4
}
Payload:
{
   "iss": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6050a61",
   "exp": 1551903163,
   "aud": [
   "968c2306-9aef-4109-bc06-4f5ed6axi24a"
   ],
   "sub": "2b96cc04-eca5-4122-a8de-6e07d14c13a5",
   "email_verified": true,
   "amr": [
   "cloud_directory"
   ],
   "iat": 1551899553,
   "tenant": "39a37f57-a227-4bfe-a044-93b6e6050a61",
   "scope": "openid appid_default appid_readprofile appid_readuserattr appid_writeuserattr appid_authenticated"
}

識別トークン

識別トークンとは認証を表すものであり、ユーザーに関する情報が含まれています。名前、E メール、性別、場所に関する情報を提供できます。トークンはユーザーのイメージへの URL を返すこともできます。トークンは JSON Web トークンとしてフォーマットされ、 RS256 アルゴリズムを使用する JSON Web 鍵で署名されます。

トークンの例:

Header:
{
   "alg": "RS256",
   "typ": "JWT",
   "kid": "appId-39a37f57-a227-4bfe-a044-93b6e6050a61-2018-08-02T11:57:43.401",
   "ver": 4
}
Payload:
{
   "iss": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6050a61",
   "aud": [
   "968c2306-9aef-4109-bc06-4f5ed6axi24a"
   ],
   "exp": 1551903163,
   "tenant": "39a37f57-a227-4bfe-a044-93b6e6050a61",
   "iat": 1551899553,
   "email": "appid155@mailinator.com",
   "name": "appid155@mailinator.com",
   "sub": "2b96cc04-eca5-4122-a8de-6e07d14c13a5",
   "email_verified": true,
   "identities": [
   {
      "provider": "cloud_directory",
      "id": "118c0278-3526-4954-876b-cf70eb88efa2"
   }
   ],
   "amr": [
   "cloud_directory"
   ]
}

識別トークンには、部分的なユーザー情報のみが含まれます。 ID プロバイダーによって提供されるすべての情報を表示するには、/userinfo エンドポイントを使用できます。

リフレッシュ・トークン

App ID は、 OIDC で定義されているように、再認証なしで新しいアクセス・トークンおよび ID トークンを取得する機能をサポートしている。リフレッシュ・トークンを使用してアクセス・トークンを更新すれば、ユーザーはサインインのための操作 (資格情報の入力など) を行わなくてもよくなります。アクセス・トークンと同様、リフレッシュ・トークンには、許可されたユーザーかどうかを App ID が判別できるデータが含まれています。ただし、このトークンは内部が見えない状態になっています。

リフレッシュ・トークンは、通常のアクセス・トークンより存続期間が長くなるように構成されています。そのため、アクセス・トークンが期限切れになっても、リフレッシュ・トークンは引き続き有効であり、アクセス・トークンを更新するために使用できます。 App ID のリフレッシュ・トークンは、1 日から 90 日の範囲で存続期間を構成できます。リフレッシュ・トークンを最大限に活用するには、トークンの存続期間が満了するかトークンが更新されるまでトークンを持続させておきます。ユーザーはリフレッシュ・トークンだけではリソースに直接アクセスすることができないため、アクセス・トークンを持続させておくよりリフレッシュ・トークンを持続させておく方がずっと安全です。ベスト・プラクティスとして、リフレッシュ・トークンは、それを受信したクライアントで安全に保管し、その発行元となった許可サーバーにのみ送信するようにしてください。

利便性の向上のために、App ID は、アクセス・トークンの更新時にリフレッシュ・トークン (およびその有効期限) も更新します。これによりユーザーは、現行のリフレッシュ・トークンが期限切れになる前のいずれかの時点でアクティブであれば、ログインした状態を保つことができます。一方、リフレッシュ・トークンを使用するものの、ユーザーに定期的なログインを強制する場合は、ユーザーが資格情報を入力してログインしたときに返されるリフレッシュ・トークンのみをアプリで使用するようにします。ただし、 OAuth 2.0 の仕様に記載されているように、 App ID から受信した最新のリフレッシュトークンを常に使用することをお勧めします。

このトークンはログイン・プロセスの合理化に役立つとはいえ、それに依存するアプリは作成しないようにしてください。リフレッシュ・トークンは、漏えいが疑われる場合などにいつでも取り消すことができます。必要に応じて、2 つの方法でリフレッシュ・トークンを取り消すことができます。リフレッシュ・トークンを持っている場合、以下の方法でそれを取り消すことができます。 RFC7009. あるいは、ユーザーIDがあれば、 Management APIを使ってリフレッシュ・トークンを取り消すこともできます。管理APIへのアクセスの詳細については、サービスアクセスの管理を参照してください。

リフレッシュ・トークンの処理の例や、リフレッシュ・トークンを使用してユーザー情報を記憶させる機能を実装する方法については、概説のサンプルを参照してください。

トークンの発行元

トークンは、 App ID OAuth Serverを通じて発行され、 JSON Web Tokens（JWT ）としてフォーマットされます。トークンは、 RS256 アルゴリズムを使用する JSON Web Key(JWK) で署名されています。

トークンに含まれる情報の扱い

アクセス・トークンには、一連の標準 JWT クレームと、一連の App ID 固有クレーム (テナント ID など) が格納されます。識別トークンには、ユーザー固有の情報が含まれます。トークン内の情報は、ユーザー・プロファイルの一部となるクレームとして保管されます。

トークンの受信方法

認証が成功すると、アプリがトークンを受信します。アプリでは、トークンを使用して、ユーザーの許可と認証に関する情報を取得します。アクセス・トークンを使用すると、保護リソースに要求を送信して、リソースへのアクセス権限を得ることができます。アプリは、トークンを抽出するためにヘッダーを解析する必要があります。

要求例:

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer  mF_9.B5f-4.1JqM mF_9.B5f-4.1JqM

トークンの構成方法

カスタムのクレーム・マッピングを使用して、トークンをカスタマイズできます。詳しくは、トークンのカスタマイズを参照してください。