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:
- Users obtain JWT from an Identity Provider (eg. Auth0)
- They use it to call the service API endpoint
- The service posts an authorization request on Doorman to check if the user is allowed
-
Doorman uses the
Origin
request header to select the set of policies - 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:
- Users call the service API endpoint
- The service authenticates the user and builds the list of principals
- 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
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 theroles
context field will expand the principals with extrarole:{}
values.
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.
With JWT verification enabled, a valid JSON Web Token (JWT) must be provided in the Authorization
request header. (eg. Bearer eyJ0eXAiOiJKV1QiLCJhbG...9USXpOalEzUXpV
)
Request Content-Types: application/json
Request Example
{
"principals": [
"userid:ldap|ada",
"email:ada@lau.co"
],
"action": "create",
"resource": "comment",
"context": {
"env": [
"stage"
],
"roles": [
"changer"
]
}
}
Return whether it is allowed or not.
Missing headers or invalid posted data.
JWT token is invalid.
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
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)
Reloaded successfully.
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?
Server working properly
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?
Server reachable
Response Content-Types: application/json
Response Example (200 OK)
{
"ok": true
}
Running instance version information
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.
Return the Open Api Specification.
Response Content-Types: application/json
Response Example (200 OK)
"object"
Open source contributing information
Return open source contributing information.
Response Content-Types: application/json
Response Example (200 OK)
"object"