As a Resource Owner/Controller (and perhaps as a Resource User too),
I want the Authorization Service to explain me why exactly certain access has been granted/denied,
So that I can understand/explain the decisions, and make changes to policies if needed.

Preconditions:

• A Resource Owner/Controller can manage policies over some resources on an LWS-compatible resource server.
• Resource Users interact with the RO/RC's Authorization Server and Resource Servers to access resources.
• The Authorization Service has granted/denied a certain access request.

Trigger:

The RO/RC wants an explanation for a certain policy decision.

Actors:

• [Primary] The Resource Owner/Controller (~ Data Holder/Supplier): an agent who has partial/delegated (controller) or ultimate (owner) control over policies concerning certain resources.

• [Technical] The Authorization Service: the access management system used by the RO/RC to protect their resources on the RS.

Distinction:

With any non-trivial set of policies, the Authorization Service might make decisions (granting or denying permission) of which it is not immediately clear how they follow from those policies. In those cases, an RO/RC might desire an explanation, in order to understand the decision and possibly update the policy set. Such an explanation must be as humanly understandable as possible.

Scenario:

1. The RO/RC accesses their Authorization Service's overview of recent decisions, and select the decision they don't understand.
2. Included in the details of the decision, they find
   • the policies on which the decision was based,
   • the parameters included in the decision process (e.g. context, credentials provided by the RU etc.), and
   • a description of which (logical) steps the policy engine has taken to result in that particular decision.

Alternative case(s):

• Next to a static explanation, one could envision a scenario in which the RO/RC can interact with the Authorization Service, and ask more questions concerning specific details of the explanation, which are then further clarified.

• Sometimes an explanation might not be understood, or even indicate a possible problem/fault with the policy engine. In this case, the RO/RC should be able to escalate the issue to the system management level.

Error scenario:

• The full explanation might be to complicated to present in any humanly understandable manner.
• Transforming the technical decision details into a humanly understandable explanation might take too long or time out (performance-wise).

Acceptance Criteria:

• RO/RCs can access the details of decisions made by the Authorization Service.
• In the details of a decision, RO/RCs can find a humanly understandable explanation of why the decision in question has been made.