Introducing Pauldron: An Experimental UMA Server

Sunday. January 28, 2018 - 5 mins

(also posted here).

Summary: Meet Pauldron, an experimental authorization server based on User-Managed Access (UMA) profile of OAuth 2.0 with some additional extensions.

In the last few months, I have spent some of my personal time working on an experimental UMA server in order to have a platform for testing various developing ideas around authorization. The project is called Pauldron, after the name of the piece of armor which covers the shoulder and connects the body piece and arm piece. Just like the armor piece, the goal of Pauldron is to protect and integrate.

As I continue working on Pauldron in my personal time depending on my availability, I decided to released it on GitHub as an open-source project under MIT license. In the rest of this post I will briefly introduce some of the main ideas in Pauldron and the roadmap for its future.

Extensions to UMA

The following extensions are currently implemented in Pauldron:

Cascaded Authorization

The ability to require another UMA server’s approval as a pre-requisite for the approval of this server. For an introduction to the idea of Cascaded Authorization check out this HL7 draft white paper. The Access Token from the secondary Pauldron server is submitted by the Client as a Claims Token and the claims in the introspection response for that Access Token can be referenced in the server’s authorization policy to make authorization decisions.

Policy Endpoint

The policy endpoint enables dynamically adding/removing authorization policies to govern the server’s authorization decisions, i.e. whether to issue an Access Token, and what scopes to grant. The policy can reference the claims provided by the Client (and in future, Resource Set attributes) as decision factors.

JSON Scopes

Unlike most existing UMA/OAuth 2.0 implementations, scopes (and Resource Set IDs) are not limited to plain strings and can be any JSON objects. This enables modeling complex scopes flexibly without having to encode them into strings based on arbitrary grammars (for a discussion on this, check out this post).

Compartmentalization of Resource Servers based on Domains

Resource Servers are grouped into Domains. A Resource Server only gets a successful introspection response for an Access Token if it is issued based on a Ticket which has been originally issued at the request of a Resource Server belonging to the same Domain. Thus, if a Client receives a valid Access Token based on a Ticket from a Resource Server in one domain, and then presents this Access Token to a Resource Server belonging to another domain, the introspection will deem that Access Token invalid. For simplicity, when a Resource Server does not have a domain property set, it is assumed to belong to its own one-server domain with the domain ID being its client_id.

Planned Features

I am planning to add the following extensions to Pauldron in future.

One of the important use-cases for Pauldron is using it to protect a FHIR Resource Server. So, it is important that Pauldron be able to process FHIR Consents as authorization policy to control access to a patient’s information. This will be in the form of submitting a reference to a FHIR server where Consents are stored.

Other Types of Tokens for Client Authentication and Claims

Currently, the only accepted types of Claims Token for the Client are JWTs by an issuer known to the Pauldron server via a shared secret key. Supporting asymmetrically-signed Claims Tokens, and more specific support for OpenID Connect and SAML tokens is upcoming. Later, I would also like to support blockchain-based claims tokens based on Decentralized Identifiers (DID).

Two-Legged Mode

For a simpler flow and for certain types of Clients, it is desirable to let the Client directly request a set of Permissions from the Authorization Endpoint instead of presenting a Ticket from a Resource Server (after Permission Registration). This will allow a simpler flow where the Permission Registration and initial interaction with the Resource Server by the Client is eliminated.

Privacy-Preserving Authorization

In systems where there are multiple (perhaps dynamically changing) Resource Servers, the Client often needs to use some form of discovery service to find their address. The Resource Set Registration API (currently not implemented) can be leveraged to use the Authorization Server as a discovery mechanism for Resource Servers. This makes the flow simpler by merging the discovery step into the authorization flow and also makes it possible to enforce access control on the discovery process so that Clients can only discover Resource Servers they are authorized to talk to. In this flow, the Client requests an Access Token with a specific set of Permissions from the Pauldron Server, and in response, receives an Access Token together with a list of Resource Servers which host the Resource Sets requested by the Client. For an introduction to the idea of Privacy Preserving Authorization check out this HL7 draft white paper.

Augmented Resource Set Registration Endpoint

To enable more flexibility in authorization policies, we need a Resource Set Registration Endpoint with a metadata extension to record arbitrary attributes about Resource Sets. These attributes can be referenced in authorization policies of the Pauldron Server to make access control decisions.

Other Types of Policies

The policy endpoint needs to be able to accept and process other types of authorization policies such as XACML and ODRL.

Aside from the main sever, I am also working on a number of additional Pauldron components to facilitate its use:

Pauldron FHIR Proxy: An experimental reverse proxy for protecting access to a FHIR server using Pauldron.
Pauldron Clients: A simple client library to facilitate communicating with different endpoints of a Pauldron server.
Pauldron Policy: A simple JSON-based policy format for expressing authorization policies.