IAM

IAM 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). It is inspired by AWS IAM Policies.

Policies

Policies are defined in YAML file (default ./policies.yaml) as follow:

  audience: https://service.stage.net
  policies:
    -
      description: One policy to rule them all.
      subjects:
        - maria
        - <[peter|ken]>
        - group:admin
      actions:
        - delete
        - <[create|update]>
      resources:
        - resources:articles:<.*>
        - resources:printer
      conditions:
        remoteIP:
          type: CIDRCondition
          options:
            cidr: 192.168.0.1/16
      effect: allow

Use effect: deny to deny explicitly.

Otherwise, requests that don't match any rule are denied.

Regular expressions begin with < and end with >.

Conditions

The conditions are optional and are used to match field values from the requested context. 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-.*

Subject comparison

• type: EqualsSubjectCondition

For example, allow requests where request.context["owner"] == request.subject:

conditions:
  owner:
    type: EqualsSubjectCondition

IP/Range

• type: CIDRCondition

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

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

API

POST /allowed

Is this subject allowed to perform this action on this resource in this context?

Requires authentication

A valid JSON Web Token (JWT) must be provided in the Authorization request header. The JWT subject is used to match the policies.

The JWT claimed audience will be checked against the Origin request header. The specified value must match one of the known audience from the policies files.

Request:

POST /allowed HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...9USXpOalEzUXpV

{
  "action" : "delete",
  "resource": "resource:articles:ladon-introduction",
  "context": {
    "remoteIP": "192.168.0.5"
  }
}

Response:

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

{
  "allowed": true,
  "user": {
    "id": "google-auth|2664978978"
  }
}

More

• See full API spec

Configuration

Via environment variables:

• 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)
• POLICIES_FILES: locations of YAML files with policies (default: ./policies.yaml)
• JWT_ISSUER: issuer of the JWT tokens to match. For JWTs issued by Auth0, use the domain with a https:// prefix and a trailing / (eg. https://auth.mozilla.auth0.com/)

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

Run locally

make serve

Or with JWT verification enabled:

make serve -e JWT_ISSUER=https://minimal-demo-iam.auth0.com/

Run tests

make test

License

• MPLv2.0