Doorman

Doorman is an authorization micro-service.

• API Documentation
• Examples

Doorman responds to authorization requests based on a set of rules (policies files).

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

Run

    docker run \
      -e POLICIES=/config \
      -v ./examples/python:/config \
      -p 8000:8080 \
      --name doorman \
      mozilla/doorman

Doorman is now ready to respond authorization requests on http://localhost:8080. See API docs.

Policies

Policies are defined in YAML files for each consuming service, locally or in remote (private) Github repos, as follow:

service: https://service.stage.net
jwtIssuer: https://auth.mozilla.auth0.com/
tags:
  superusers:
    - userid:maria
    - group:admins
policies:
  -
    id: authors-superusers-delete
    description: Authors and superusers can delete articles
    principals:
      - role:author
      - tag:superusers
    actions:
      - delete
    resources:
      - article
    effect: allow

• service: the unique identifier of the service
• jwtIssuer (optional): when the issuer is set, Doorman will verify the JSON Web Token provided in the authorization request and extract the Identity Provider information from its payload
• tags: Local «groups» of principals in addition to the ones provided by the Identity Provider
• actions: a domain-specific string representing an action that will be defined as allowed by a principal (eg. publish, signoff, …)
• resources: a domain-specific string representing a resource. Preferably not a full URL to decouple from service API design (eg. print:blackwhite:A4, category:homepage, …).
• effect: Use effect: deny to deny explicitly. Requests that don't match any rule are denied.

Principals

The principals is a list of prefixed strings to refer to the «user» as the combination of ids, emails, groups, roles…

Supported prefixes:

• userid:: provided by Identity Provider (IdP)
• tag:: local tags
• role:: provided in context of authorization request (see below)
• email:: provided by IdP
• group:: provided by IdP

Example: ["userid:ldap|user", "email:user@corp.com", "group:Employee", "group:Admins", "role:editor"]

Settings

Via environment variables:

• POLICIES: space separated locations of YAML files with policies. They can be single files, folders or Github URLs (default: ./policies.yaml)
• GITHUB_TOKEN: Github API token to be used when fetching policies files from private repositories

Advanced:

• PORT: listen (default: 8080)
• GIN_MODE: server mode (release or default debug)
• LOG_LEVEL: logging level (fatal|error|warn|info|debug, default: info with GIN_MODE=release else debug)
• VERSION_FILE: location of JSON file with version information (default: ./version.json)

Note: the Dockerfile contains different default values, suited for production.

Advanced policies rules

Regular expressions

Regular expressions begin with < and end with >.

principals:
  - userid:<[peter|ken]>
resources:
  - /page/<.*>

Note: regular expressions are not supported in tags members definitions.

Conditions

The conditions are optional on policies and are used to match field values from the authorization request context.

The context value remoteIP is forced by the server.

For example:

policies:
  -
    description: Allow everything from dev environment
    conditions:
      env:
        type: StringEqualCondition
        options:
          equals: dev

There are several types of conditions:

Field comparison

• type: StringEqualCondition

For example, match request.context["country"] == "catalunya":

conditions:
  country:
    type: StringEqualCondition
    options:
      equals: catalunya

Field pattern

• type: StringMatchCondition

For example, match request.context["bucket"] ~= "blocklists-.*":

conditions:
  bucket:
    type: StringMatchCondition
    options:
      matches: blocklists-.*

Match principals

• type: MatchPrincipalsCondition

For example, allow requests where request.context["owner"] is in principals:

conditions:
  owner:
    type: MatchPrincipalsCondition

Note: This also works when a the context field is list (e.g. list of collaborators).

IP/Range

• type: CIDRCondition

For example, match request.context["remoteIP"] with CIDR notation:

conditions:
  remoteIP:
    type: CIDRCondition
    options:
      # mask 255.255.0.0
      cidr: 192.168.0.1/16

Run from source

make serve -e POLICIES=sample.yaml

Run tests

make test

Generate API docs

make api-docs

Build docker container

make docker-build

License

• MPLv2.0
• The logo was made by Mathieu Leplatre with Inkscape and released under CC0