# AuthZEN Repository
This repository contains the output of the [OpenID AuthZEN](https://openid.net/wg/authzen/) working group.

## API spec

The AuthZEN authorization API is versioned in markdown at `api/authorization-api-1_0.md`. A GitHub workflow builds this into HTML. See the "Building the spec" section for more details.

The latest published version of the spec is available [here](https://openid.github.io/authzen).

## Draft COAZ Framework

COAZ (Compatible with OpenID AuthZEN) is a protocol-neutral framework for mapping the information model of an arbitrary protocol or interface into a request to the AuthZEN Authorization API. It is at `profiles/authzen-coaz-framework-1_0.md`. The HTML version is available [here](https://openid.github.io/authzen/authzen-coaz-framework-1_0.html).

## Draft COAZ-MCP Binding

COAZ-MCP is the COAZ binding for the Model Context Protocol (MCP), defining how MCP JSON-RPC messages map into AuthZEN Authorization API requests. It is at `profiles/authzen-coaz-mcp-binding-1_0.md`. The HTML version is available [here](https://openid.github.io/authzen/authzen-coaz-mcp-binding-1_0.html).

## Draft Access Request and Approval Profile
A profile that specifies an approval workflow for handling denials in a structured way.
The HTML version is available [here](https://openid.github.io/authzen/authzen-access-request-approval-profile-1_0.html)

## Draft OAuth 2.0 Token Issuance Profile

A profile for using the AuthZEN Authorization API to externalize an authorization server's decision to issue a token, and to let the decision response shape what is issued. It is at `profiles/authzen-oauth/authzen-oauth-token-issuance-1_0.md`. The HTML version is available [here](https://openid.github.io/authzen/authzen-oauth-token-issuance-1_0.html).

## Draft OAuth 2.0 Token Exchange Binding

The binding of the token issuance profile to OAuth 2.0 Token Exchange, covering delegation, impersonation, identity chaining, ID-JAG and Transaction Tokens. It is at `profiles/authzen-oauth/authzen-oauth-token-exchange-1_0.md`. The HTML version is available [here](https://openid.github.io/authzen/authzen-oauth-token-exchange-1_0.html).

## Draft Authorization Claims Profile

A profile that sources the `groups`, `roles` and `entitlements` claims of a JWT access token from AuthZEN Resource Search rather than from a directory or a vendor-specific hook. It is at `profiles/authzen-oauth/authzen-oauth-authorization-claims-1_0.md`. The HTML version is available [here](https://openid.github.io/authzen/authzen-oauth-authorization-claims-1_0.html).

## Interop harness

The `interop` directory contains the interoperability scenarios for AuthZEN. Currently, there is a single scenario based on a "Todo" application. The scenario spec and results can be viewed [here](https://authzen-interop.net).

* `interop/authzen-interop-website` contains the source code for the https://authzen-interop.net micro-site. It is based on the Docusaurus framework.
* `interop/authzen-todo-application` contains the source code for the Todo React front-end hosted at https://todo.authzen-interop.net.
* `interop/authzen-todo-backend` contains the source code for the (TypeScript) Todo backend.

Each of these directories contains a README for further instructions.

## Building the spec

To build the spec locally, you need two tools - `kramdown` (a Ruby gem), and `xml2rfc` (a python tool).

The GitHub workflow in `.github/workflows/jekyll-gh-pages.yml` runs on each PR that is merged to `main`, resulting in a new HTML version of the spec hosted at https://openid.github.io/authzen.

To build locally, ensure that you have both a Python and Ruby distribution.

### Install dependencies

```sh
gem install kramdown-rfc
pip install xml2rfc
```

### Build the spec

```sh
# Convert from markdown to XML
kramdown-rfc2629 api/authorization-api-1_0.md > api/authorization-api-1_0.xml

# Render XML into HTML
xml2rfc api/authorization-api-1_0.xml --html -o index.html
```