# XACML 3.0 Profile of OpenID AuthZEN 1.0

[TOC]

## About this document

OpenID AuthZEN defines a set of APIs to communicate between policy enforcement points (PEP) and policy decision points (PDP). While many authorization frameworks do not formally define a request/response format, such as Open Policy Agent, Cedar, or Graph-based approaches, XACML-based frameworks already adhere to a request/response format defined in the core specification and two additional profiles:
- [eXtensible Access Control Markup Language (XACML) Version 3.0](https://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html), OASIS Standard, January 2013
- [JSON Profile of XACML 3.0 Version 1.1](https://docs.oasis-open.org/xacml/xacml-json-http/v1.1/xacml-json-http-v1.1.html), OASIS Standard, June 2019
- [XACML REST Profile Version 1.1](https://docs.oasis-open.org/xacml/xacml-rest/v1.1/xacml-rest-v1.1.html), OASIS Standard, June 2019

This document aims to provide a deterministic mapping/translation:
- from an OpenID AuthZEN request into a XACML request
- from a XACML response into an OpenID AuthZEN response

The aforementioned will allow existing XACML-based PDPs to process incoming AuthZEN requests and issue valid AuthZEN responses. In addition, this profile also defines a mapping/translation:

- from a XACML request into an OpenID AuthZEN request
- from an OpenID AuthZEN response into a XACML response.

This is useful in the event an existing XACML-based Policy Enforcement Point needs to be integrated with an AuthZEN-based PDP.

The AuthZEN APIs in scope are:
- The Binary Authorization API and
- The Batch Binary Authorization API.

The AuthZEN APIs out of scope are:
- The Subject Search API,
- The Resource Search API, and
- The Action Search API.

## Mapping from OpenID AuthZEN Request into XACML Request

The information model for an OpenID AuthZEN Request is defined in [6.1. The Access Evaluation API Request](https://openid.github.io/authzen/#name-the-access-evaluation-api-r). A request is made up of four entities. Each entity maps into a XACML category as defined hereafter:

### Mechanism to map categories/entities

In XACML, a request is made up of categories (technically an unbounded array of `Attributes` elements. Each `Attributes` member has a `CategoryId` which determines the category it belongs to). There are default categories defined in XACML and _generally_ a XACML request is made up of a subject, action, resource, and environment category.

### Default Mappings

The 4 entities in AuthZEN will map to the following 4 categories in XACML:

| **Category** | **AuthZEN Entity Name** | **XACML Category ID** | **XACML JSON Shorthand** |
|-|-|-|-|
|Subject|`subject`|`urn:oasis:names:tc:xacml:1.0:subject-category:access-subject`|`AccessSubject`|
|Action|`action`|`urn:oasis:names:tc:xacml:3.0:attribute-category:action`|`Action`|
|Resource|`resource`|`urn:oasis:names:tc:xacml:3.0:attribute-category:resource`|`Resource`|
|Context|`context`|`urn:oasis:names:tc:xacml:3.0:attribute-category:environment`|`Environment`|

### Default Request Translation Process

1. When an OpenID AuthZEN request is received, members of the entities aforementioned will become attributes of the corresponding XACML category.
2. Each member of each entity will be converted into a member of the `Attribute` array in the corresponding category in XACML.
3. The value of `AttributeId` will be the name of the key in AuthZEN.
4. The value of `Value` will be the value associated to the given key in AuthZEN e.g. `[e-mail]` in the case of `id` in the `subject` entity.
5. The members of the `properties` entity will be mapped as entries in the `Attribute` array following the same process described in steps 2 and 3.

The following is a non-normative example

|**AuthZEN Request**|**XACML JSON Equivalent**|
|-|-|
|<pre>{<br/> "subject": {<br/> "type": "user",<br/> "id": "[e-mail]"<br/> },<br/> "resource": {<br/> "type": "account",<br/> "id": "123"<br/> },<br/> "action": {<br/> "name": "view",<br/> "properties": {<br/> "method": "GET"<br/> }<br/> },<br/> "context": {<br/> "time": "1985-10-26T01:22-07:00"<br/> }<br/>}<br/></pre>|<pre>{"Request":<br/> { <br/> "AccessSubject":<br/> {"Attribute":<br/> [<br/> {"AttributeId":"type","Value":"user"}<br/> ]<br/> },<br/> "Action":<br/> {"Attribute":<br/> [<br/> {"AttributeId":"name","Value":"view"},{"AttributeId":"method","Value":"GET"}<br/> ]<br/> },<br/> "Resource":<br/> {"Attribute":<br/> [<br/> {"AttributeId":"type","Value":"account"},<br/> {"AttributeId":"id","Value":"123"}<br/> ]<br/> },<br/> "Environment":<br/> {"Attribute":<br/> [<br/> {"AttributeId":"time","Value":"1985-10-26T01:22-07:00"}<br/> ]<br/> }<br/> }<br/>}<br/>
</pre>|

### Custom Mappings

To provide additional flexibility, an AuthZEN to XACML request mapper can allow for a mapping file that overrides the creation of the `Attribute` element in XACML.
The mapping file contains keys that uniquely identify the AuthZEN request element using its fully qualified name e.g.:
- `subject.type`,
- `subject.properties.location`

Each FQN from the AuthZEN request is an entity made up:
- A XACML attribute identifier,
- A XACML category identifier (optional),
- A XACML datatype identifier (optional) using the shorthand notation as defined in the JSON Profile of XACML 3.0 Version 1.1,
- The XACML boolean flag `IncludeInResult` (optional), and
- The XACML field `Issuer` (optional).

A mapping file does not need to contain all possible mappings but only those for which the behavior needs to be customized.

The following is a non-normative example of a mapping file used in the AuthZEN-to-XACML request mapping process.

subject.id:
    - AttributeId: "com.acme.username"
    - Category: AccessSubject
    - DataType: string
    - IncludeInResult: false
    - Issuer: false
resource.properties.location:
    - AttributeId: "com.acme.record.country"

## Mapping from XACML Response into OpenID AuthZEN Response

### Mapping the decision
While XACML allows for 4 decisions, `Permit`, `Deny`, `NotApplicable`, and `Indeterminate`, AuthZEN only allows for `true`/`false`.

By default, the mapper MUST translate all `Permit` decisions into a `true`. All other decisions are `false`. This behavior is known as deny bias.

It is possible to override the bias by define a mapping file with the following property:

decision
    - true : ["Permit","NotApplicable"]

Any XACML decision not listed in the custom mapping will result in a decision of `false`.

### Mapping Obligations & Advice

### Mapping Attributes included in Response

### Mapping Policy Identifiers