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 thisaction
on thisresource
in thiscontext
?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: - 400 Bad Request – Missing headers or invalid posted data.
- 401 Unauthorized – OpenID token is invalid.
- 200 OK – Return whether it is allowed or not.
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: - 200 OK – Reloaded successfully.
- 500 Internal Server Error – Reload failed.
-
GET
/__heartbeat__
¶ Is the server working properly? What is failing?
Status Codes: - 200 OK – Server working properly
- 503 Service Unavailable – One or more subsystems failing.
-
GET
/__version__
¶ Running instance version information
Status Codes: - 200 OK – Return the running instance version information