API

Summary

Basically, authorization requests are checked using POST /allowed.

  • The Origin request header specifies the service to match policies from.
  • The Authorization request header provides the OpenID Access Token to authenticate the request.

Request:

POST /allowed HTTP/1.1
Origin: https://api.service.org
Authorization: Bearer f2457yu86yikhmbh

{
  "action" : "delete",
  "resource": "articles/doorman-introduce",
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "allowed": true,
  "principals": [
    "userid:ada",
    "email:ada.lovelace@eff.org",
    "group:scientists",
    "group:history"
  ]
}

Principals

The authorization request :term:principals will be built from the user profile information like this:

  • "sub": userid:{}
  • "email": email:{} (optional)
  • "groups": group:{}, group:{}, ... (optional)

They will be matched against those specified in the policies rules to determine if the authorization request is denied or allowed.

Authentication

Doorman relies on OpenID to authenticate requests.

It will use the service and identityProvider fields from the service policies file to fetch the user profile information.

The Origin request header should match one of the services defined in the policies files.

The Authorization request header should contain a valid Access Token, prefixed with Bearer ``. This access token must have been requested with the ``openid profile scope for Doorman to be able to fetch the profile information (See Auth0 docs).

The userinfo URI endpoint is then obtained from the metadata available at {identityProvider}/.well-known/openid-configuration.

If the obtention of user infos is denied by the Identity Provider, the authorization request is obviously denied.

Using ID tokens

Doorman can verify and read user information from JWT ID tokens. Since the ID token payload contains the user information, it saves a roundtrip to the Identity Provider when handling authorization requests.

For this to work, the service value in the policies file must match the audience value configured on the Identity Provider — the unique identifier of the target API. For example, in Auth0 it can look like this: SLocf7Sa1ibd5GNJMMqO539g7cKvWBOI.

Important

When using JWT ID tokens, only the validity of the token will be checked. In other words, users that are revoked from the Identity Provider after their ID token was issued will still considered authenticated until the token expires.

Without authentication

If the identity provider is not configured for a service (explicit empty value), no authentication is required and the principals are posted in the authorization body.

POST /allowed HTTP/1.1
Origin: https://api.service.org
Authorization: Bearer f2457yu86yikhmbh

{
  "action" : "delete",
  "resource": "articles/doorman-introduce",
  "principals": [
    "userid:mickaeljfox",
    "email:mj@fox.com",
    "group:actors"
  ]
}

It is not especially recommended, but it can give a certain amount of flexibility when authentication is fully managed on the service.

A typical workflow in this case would be:

1. Users call the service API endpoint 1. The service authenticates the user and builds the list of principals 1. The service posts an authorization request on Doorman containing the list of principals to check if the user is allowed

Context

Authorization requests can carry additional information contain any extra information to be matched in policies conditions.

The values provided in the roles context field will expand the principals with extra role:{} values.

POST /allowed HTTP/1.1
Origin: https://api.service.org
Authorization: Bearer f2457yu86yikhmbh

{
  "action" : "delete",
  "resource": "articles/doorman-introduce",
  "context": {
    "env", "stage",
    "roles": ["editor"]
  }
}

API Endpoints

(Automatically generated from the OpenAPI specs)

POST /allowed

Check authorization request

Are those principals allowed to perform this action on this resource in this context?

With authentication enabled, the principals are either read from the Identity Provider user info endpoint or directly from the JSON Web Token payload if an ID token is provided.

Status Codes:
Request Headers:
 
  • Origin – The service identifier (eg. https://api.service.org). It must match one of the known service from the policies files.
  • Authorization – With OpenID enabled, a valid Access token (or JSON Web ID Token) must be provided in the Authorization request header. (eg. Bearer eyJ0eXAiOiJKV1QiLCJhbG…9USXpOalEzUXpV)
POST /__reload__

Reload the policies

Reload the policies (synchronously). This endpoint is meant to be used as a Web hook when policies files were changed upstream.

> It would be wise to limit the access to this endpoint (e.g. by IP on reverse proxy)

Status Codes:
GET /__heartbeat__

Is the server working properly? What is failing?

Status Codes:
GET /__lbheartbeat__

Is the server reachable?

Status Codes:
GET /__version__

Running instance version information

Status Codes:
  • 200 OK – Return the running instance version information
GET /__api__

Open API Specification documentation.

Status Codes:
  • 200 OK – Return the Open Api Specification.
GET /contribute.json

Open source contributing information

Status Codes:
  • 200 OK – Return open source contributing information.