AuthZENのAuthorization APIとは（４）

こんにちは、富士榮です。

引き続きAuthZEN WGのAuthorization API 1.0のdraftを見ていきます。

https://openid.net/specs/authorization-api-1_0-01.html

今回はいよいよPEP（ポリシー実施ポイント）とPDP（ポリシー決定ポイント）の間のAPI仕様の部分です。

6. Access Evaluation API

The Access Evaluation API defines the message exchange pattern between a client (PEP) and an authorization service (PDP) for executing a single access evaluation.

6.アクセス評価API

アクセス評価 API は、単一のアクセス評価を実行するためのクライアント (PEP) と認可サービス (PDP) 間のメッセージ交換パターンを定義します

 まずはリクエストからです。

6.1. The Access Evaluation API Request

The Access Evaluation request is a 4-tuple constructed of the four previously defined entities:

• subject: REQUIRED. The subject (or principal) of type Subject
• action: REQUIRED. The action (or verb) of type Action.
• resource: REQUIRED. The resource of type Resource.
• context: OPTIONAL. The context (or environment) of type Context.

6.1.アクセス評価APIリクエスト

アクセス評価リクエストは、以前に定義された4つのエンティティから構成される4つのタプルです: 

• subject: 必須。Subject 型のサブジェクト（またはプリンシパル）
• action: 必須。アクション型のアクション（または動詞）
• resource: 必須。リソースタイプのリソース
• context: オプション。Context 型のコンテキスト (または環境) 

{
  "subject": {
    "type": "user",
    "id": "alice@acmecorp.com"
  },
  "resource": {
    "type": "account",
    "id": "123"
  },
  "action": {
    "name": "can_read",
    "properties": {
      "method": "GET"
    }
  },
  "context": {
    "time": "1985-10-26T01:22-07:00"
  }
}

Figure 9: Example Request

データセットは前回見てきた通りですね。

誰（subject）が何（resource）に対して何を（action）ができるかを問い合わせるわけですね。上記の例だとalice@acmecorp.comという主体が123というアカウントの情報を読み取ることができるか？ということを問い合わせています。もちろんコンテキストの情報も判断基準になります。

次はレスポンスです。

6.2. The Access Evaluation API Response

The simplest form of a response is simply a boolean representing a Decision, indicated by a "decision" field.

decision: REQUIRED. A boolean value that specifies whether the Decision is to allow or deny the operation.

In this specification, assuming the evaluation was successful, there are only 2 possible responses:

• true: The access request is permitted to go forward.
• false: The access request is denied and MUST NOT be permitted to go forward.

The response object MUST contain this boolean-valued Decision key.

6.2.アクセス評価APIレスポンス

応答の最も単純な形式は、decisionフィールドによって示される決定を表すブール値です

decision: 必須。Decision が操作を許可するか拒否するかを指定するブール値

この仕様では、評価が成功したと仮定すると、可能な応答は2つだけです: 

• true: アクセス要求は続行が許可されます
• false: アクセス要求は拒否され、続行を許可してはなりません

レスポンスオブジェクトには、このブール値の Decision キーが含まれている必要があります

{
  "decision": true
}

Figure 10: Example Decision

決定された結果がdecisionとしてtrue/falseで返却されるわけですね。

前回のデータセットのactionの部分でcan_readなどはリクエストに使ってレスポンスは単純にbooleanで返すわけです。まぁシンプルではありますが、リクエストのactionのパターンをどこまで標準として定義できるかどうか？にかかってきそうです。

6.2.2. Additional Context in a Response

In addition to a "decision", a response may contain a "context" field which can be any JSON object. This context can convey additional information that can be used by the PEP as part of the decision evaluation process. Examples include:

• XACML's notion of "advice" and "obligations"
• Hints for rendering UI state
• Instructions for step-up authentication

6.2.2.レスポンス内の追加コンテキスト

"decision"に加えて、レスポンスには任意の JSON オブジェクトの"context"フィールドが含まれる場合があります。このコンテキストは、PEP が意思決定評価プロセスの一部として使用できる追加情報を伝えることができます。例: 

• XACML の「アドバイス」と「義務」の概念
• UI 状態をレンダリングするためのヒント
• ステップアップ認証の手順

 responseには追加の情報を含めることができるんですね。これによりPEP側でとるべきアクションをある程度標準として定義しておくことができそうです。

6.2.3. Example Context

An implementation MAY follow a structured approach to "context", in which it presents the reasons that an authorization request failed.

• A list of identifiers representing the items (policies, graph nodes, tuples) that were used in the decision-making process.
• A list of reasons as to why access is permitted or denied.

6.2.3.コンテキストの例

実装は、認可リクエストが失敗した理由を提示する"context"に対する構造化されたアプローチに従っても良い 

• 意思決定プロセスで使用された項目 (ポリシー、グラフ ノード、タプル) を表す識別子のリスト 
• アクセスが許可または拒否される理由のリスト

要するに単にtrue/falseの結果だけではなく理由などの情報をレスポンスに含めることができるということですね。

6.2.3.1. Reasons

Reasons MAY be provided by the PDP.

6.2.3.1.1. Reason Field

A Reason Field is a JSON object that has keys and values of type string. The following are non-normative examples of Reason Field objects:

6.2.3.1.理由

理由は PDP によって提供される場合があります

6.2.3.1.1.理由フィールド

Reason フィールドは、String型のキーと値を持つ JSON オブジェクトです。以下は、Reason フィールド オブジェクトの非規範的な例です: 

{
  "en": "location restriction violation"
} 

Figure 11: Example Reason 

主に失敗の場合の理由の提供方法ですね。

6.2.3.1.2. Reason Object

A Reason Object specifies a particular reason. It is a JSON object that has the following fields:

• id: REQUIRED. A string value that specifies the reason within the scope of a particular response.
• reason_admin: OPTIONAL. The reason, which MUST NOT be shared with the user, but useful for administrative purposes that indicates why the access was denied. The value of this field is a Reason Field object (Section 6.2.3.1.1).
• reason_user: OPTIONAL. The reason, which MAY be shared with the user that indicates why the access was denied. The value of this field is a Reason Field object (Section 6.2.3.1.1).

The following is a non-normative example of a Reason Object:

6.2.3.1.2.理由オブジェクト

Reason オブジェクトは特定の理由を指定します。これは次のフィールドを持つ JSON オブジェクトです: 

• id: 必須。特定の応答の範囲内で理由を指定する文字列値
• reason_admin: オプション。ユーザーと共有してはならない理由ですが、アクセスが拒否された理由を示す管理目的に役立ちます。このフィールドの値は、Reason Field オブジェクト (セクション 6.2.3.1.1 )です
• reason_user: オプション。アクセスが拒否された理由をユーザーと共有する場合があります。このフィールドの値は、Reason Field オブジェクト (セクション 6.2.3.1.1 )です

以下は、Reason オブジェクトの非規範的な例です: 

{
  "id": "0",
  "reason_admin": {
    "en": "Request failed policy C076E82F"
  },
  "reason_user": {
    "en-403": "Insufficient privileges. Contact your administrator",
    "es-403": "Privilegios insuficientes. Póngase en contacto con su administrador"
  }
}

Figure 12: Example of a Reason Object

{
  "decision": true,
  "context": {
    "id": "0",
    "reason_admin": {
      "en": "Request failed policy C076E82F"
    },
    "reason_user": {
      "en-403": "Insufficient privileges. Contact your administrator",
      "es-403": "Privilegios insuficientes. Póngase en contacto con su administrador"
    }
  }
}

Figure 13: Example Response with Context

理由は割と詳しく書くことができるようです。

ただ現状はここまでしか定義がないので、実際に中身の書き方をどうするか、や言語セットのデフォルトの扱いをどうするのか、、などはこれから決めていかないといけないと思います。

ということでAPI仕様はここまでです。

次回はTransportです。