Mozilla Doorman API Reference

Doorman is an authorization micro-service that allows to checks if an arbitrary subject is allowed to perform an action on a resource, based on a set of rules (policies).

Having a centralized access control service has several advantages:

  • it clearly dissociates authentication from authorization
  • it provides a standard and generic permissions system to services developers
  • it facilitates permissions management across services (eg. makes revocation easier)
  • it allows authorizations monitoring, metrics, anomaly detection

Workflow with JWT

When the JWT issuer is configured for a service, a typical workflow is:

  1. Users obtain JWT from an Identity Provider (eg. Auth0)
  2. They use it to call the service API endpoint
  3. The service posts an authorization request on Doorman to check if the user is allowed
  4. Doorman uses the Origin request header to select the set of policies
  5. Doorman builds a list of strings (principals) for this user, and matches the policies

Doorman will verify that the specified JSON Web Token (JWT) is valid. The claimed audience in the token ("aud") will be checked against the Origin request header.

The authorization request principals will be built from the JWT payload:

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

Without JWT

If the JWT issuer is not configured for a service, no authentication is required and the principals are posted in the authorization body.

A typical workflow in this case would be:

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

API Summary

Basically, use POST /allowed to check authorization requests.

Request:


          POST /allowed HTTP/1.1
          Origin: https://api.service.org
          
          {
            "principals": ["userid:myself"]
            "action" : "delete",
            "resource": "articles/doorman-introduce",
            "context": {
              "env": "stage",
              "roles": ["editor"]
            }
          }
          

Response:


          HTTP/1.1 200 OK
          Content-Type: application/json
          
          {
            "allowed": true,
            "principals": [
              "role:editor",
              "userid:myself"
            ]
          }
          
Version: 0.1

Doorman

Main API endpoints.

Check authorization request

POST /allowed

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

With JWT verification enabled, the principals are read from the JWT payload.

Authorization request as JSON.

Note that every field is optional.

principals: string[]

Only with JWT verification disabled

Arbitrary list of strings (eg. userid:alice, group:editors).

action: string

Any domain specific action (eg. read, delete, signoff)

resource: string

Any resource (eg. blocklist, /update/rules/35)

context: object

The context can contain any extra information to be matched in policies conditions. The context field remoteIP will be forced by the server. The values provided in the roles context field will expand the principals with extra role:{} values.

Origin

The service identifier (eg. https://api.service.org). It must match one of the known service from the policies files.

With JWT verification enabled, the claimed audience in the JWT will be checked against the value of this header.

type
string
in
header
Authorization

With JWT verification enabled, a valid JSON Web Token (JWT) must be provided in the Authorization request header. (eg. Bearer eyJ0eXAiOiJKV1QiLCJhbG...9USXpOalEzUXpV)

type
string
in
header
Request Content-Types: application/json
Request Example
{
  "principals": [
    "userid:ldap|ada",
    "email:ada@lau.co"
  ],
  "action": "create",
  "resource": "comment",
  "context": {
    "env": [
      "stage"
    ],
    "roles": [
      "changer"
    ]
  }
}
200 OK

Return whether it is allowed or not.

400 Bad Request

Missing headers or invalid posted data.

401 Unauthorized

JWT token is invalid.

403 Forbidden

JWT claimed audience is invalid (authorization failed).

Response Content-Types: application/json
Response Example (200 OK)
{
  "allowed": true,
  "principals": [
    "userid:ldap|ada",
    "email:ada@lau.co",
    "tag:mayor",
    "role:changer"
  ]
}
Response Example (400 Bad Request)
{
  "message": "Missing `Origin` request header"
}

Reload the policies

POST /__reload__

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

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

200 OK

Reloaded successfully.

500 Internal Server Error

Reload failed.

Response Content-Types: application/json
Response Example (200 OK)
{
  "success": true
}
Response Example (500 Internal Server Error)
{
  "success": false,
  "message": "could not parse YAML in \"https://github.com/ops/conf/policies.yaml\""
}

Utilities

Operational and metadata endpoints.

Is the server working properly? What is failing?

GET /__heartbeat__
200 OK

Server working properly

503 Service Unavailable

One or more subsystems failing.

Response Content-Types: application/json
Response Example (200 OK)
"object"
Response Example (503 Service Unavailable)
"object"

Is the server reachable?

GET /__lbheartbeat__
200 OK

Server reachable

Response Content-Types: application/json
Response Example (200 OK)
{
  "ok": true
}

Running instance version information

GET /__version__
200 OK

Return the running instance version information

Response Content-Types: application/json
Response Example (200 OK)
{
  "source": "https://github.com/mozilla/doorman",
  "version": "1.0",
  "commit": "490ed70efff482d17a",
  "build": "20171102"
}

Open API Specification documentation.

GET /__api__
200 OK

Return the Open Api Specification.

Response Content-Types: application/json
Response Example (200 OK)
"object"

Open source contributing information

GET /contribute.json
200 OK

Return open source contributing information.

Response Content-Types: application/json
Response Example (200 OK)
"object"