This repository contains the output of the OpenID AuthZEN working group.
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.
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.
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.
A profile that specifies an approval workflow for handling denials in a structured way. The HTML version is available here
A profile that lets a PDP attach mandatory, machine-readable actions -- obligations -- to an authorization decision, which the PEP must carry out in order to honor that decision. It defines the obligation object model, PEP compliance semantics, a set of normative obligation types, and a mechanism for a PDP and PEP to discover which types they mutually support. It is at profiles/authzen-obligations-profile-1_0.md. The HTML version is available here.
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.
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.
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.
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.
interop/authzen-interop-websitecontains the source code for the https://authzen-interop.net micro-site. It is based on the Docusaurus framework.interop/authzen-todo-applicationcontains the source code for the Todo React front-end hosted at https://todo.authzen-interop.net.interop/authzen-todo-backendcontains the source code for the (TypeScript) Todo backend.
Each of these directories contains a README for further instructions.
All of the documents in this repository (the API spec, the design patterns document, the profiles and the certification scenario) are written in markdown and rendered to HTML with two tools - kramdown-rfc (a Ruby gem), and xml2rfc (a python tool).
The GitHub workflow in .github/workflows/jekyll-gh-pages.yml renders every document and publishes the result to https://openid.github.io/authzen.
- On every pull request against
main, the workflow renders every document as a build check. Nothing is published. - On every push to
main(i.e. each merged PR), the workflow renders every document and then deploys the rendered HTML to GitHub Pages.
Each document is rendered in its own parallel job, driven by a build matrix at the top of the build-rfc job. A failure in one document does not stop the others from building, and the failing document is named in the job title (for example build-rfc (coaz-framework)).
Each matrix entry has the following fields:
| Field | Description |
|---|---|
name |
A short identifier for the document, used in the job title and the artifact name. |
source |
The path to the markdown source, relative to the repository root. |
html |
The file name of the rendered HTML, as it will appear under https://openid.github.io/authzen. |
extra_html |
(Optional) An additional file name to publish the same HTML under. Only the API spec uses this, to serve as the site's index.html. |
The rendered HTML and the intermediate RFC XML for each document are uploaded as a workflow artifact named rfc-<name>, so they can be downloaded and inspected from the workflow run for any PR.
To publish a new profile or other document, add an entry to the matrix.include list in .github/workflows/jekyll-gh-pages.yml:
- name: my-new-profile
source: profiles/authzen-my-new-profile-1_0.md
html: authzen-my-new-profile-1_0.htmlOnce merged to main, the document will be available at https://openid.github.io/authzen/<html>. Remember to add a link to it in this README as well.
To build locally, ensure that you have both a Python and Ruby distribution.
gem install kramdown-rfc
pip install xml2rfcThe commands below are the same ones the workflow runs. Substitute the source and html values from the matrix entry for the document you want to build.
# 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 authorization-api-1_0.html
# (Optional) Render XML into plain text
xml2rfc api/authorization-api-1_0.xml --text