Logos Authorization

This module provides the authorization object used by Logos services.

In a Logos project, authentication is performed by a central authentication service. However, each service is responsible for defining and enforcing its own authorization rules. Since communication happens over asynchronous channels, the authentication information must be passed in each request, and the authorization object constructed by the receiving service based on this information. This module does not provide any authentication logic, but it does provide the logic for taking authentication information and converting it to authorization data based on the service's authorization rules.

Authentication Information

To produce an authorization object, authentication data must be provided. This section provides an overview of the authentication data the authorization expects to produce an authorization object.

User

Basic user information must be provided with the following properties:

• id - The id of the user
• name - The name of the user
• roles - Roles the user has within the active zone

Scopes

Scopes are a mechanism for limiting the access of an authentication credential. Each scope is a string. The special scope * can be used to signify all scopes.

Scopes are especially useful for granting third-party applications access to act on behalf of a user, but only to perform certain actions.

Zones

Zones are a mechanism for partitioning data in the application. Each user may be a member of multiple zones or no zones at all. Typically, a zone is tied to an account or organization in the organization. In an authorization context, a single zone is active.

Each zone should have the following information:

• id - The id of the zone
• name - The name of the zone
• features - Features the zone has access to

Example

The following is an example authentication structure in JSON:

[source,json]

{ "user": { "id": "0d05121f-0432-4016-86a9-5b9532af58f9", "name": "Anna Banana", "roles": ["Admin"] }, "zone": { "id": "7cb58c1d-ed57-4b2a-aeae-33b8a28945c8", "name": "Acme Inc", "features": ["Premium"] }, "scopes": ["*"] }

Authorization Logic

An authorization object provides logic for controlling which actions the user can perform on which resources, and even what parts of a resource the user has access to.

Gates

A gate determines whether or not a user has access to perform an action on resource collection at all.

[source,javascript]

try { authorization.gate('Cat', 'view') // All good } catch (err) { // No access // err.code === 'EFORBIDDEN' }

Filters

A filter describes access to a subset of a collection. It is expressed in MongoDB query syntax.

[source,javascript]

const inputFilter = {/* Filter data */} const authFilter = authorization.filter('Cat', 'view') const filter = appendFilter(inputFilter, authFilter) // Filter can now be used in a store query

A filter can also be used to check if an action on an item is allowed.

[source,javascript]

if (authorization.isFiltered('Cat', 'modify', someCat)) { throw Forbidden('You do not have permission to modify this cat') }

Masks

A mask describe access to individual properties of a resource.

[source,javascript]

const mask = authorization.mask('Cat', 'view', someCat) for (const key of mask) { someCat.hide(key) }

They can also be used in write operations.

[source,javascript]

const input = {/* Get input somehow */}, const mask = authorization.mask('Cat', 'modify', someCat), for (const key of mask) { if (Object.hasOwnProperty.call(input, key)) { throw Forbidden(You do not have permission to modify the ${key} property of this cat) } }

Applicator

An applicator defines property values that are set for a resource when performing certain actions.

[source,javascript]

const {Path} = require('@potient/logos-util') const applicator = authorization.applicator('Cat', 'create', someCat) for (const [key, value] of Object.entries(applicator)) { Path.set(someCat, key, value, true) }

Authorization Definition

Authorization data is described in the https://yaml.org/[YAML] format and should be placed in your services data directory in file named authorize.yml.

An example authorize file might look like this:

[source,yaml]

refs:

• &view actions:
  • view filter: accountId: $zone.id scopes:
  • animals:read
• &create actions:
  • create applicator: accountId: $zone.id createdBy: $user.id modifiedBy: $user.id scopes:
  • animals:write
• &modify actions:
  • modify filter: accountId: $zone.id applicator: modifiedBy: $user.id scopes:
  • animals:write
• &delete actions:
  • delete filter: accountId: $zone.id scopes:
  • animals:write

grants:

resources: ['Cat']
grants:
  -
    roles:
      - Owner Admin
    grants:
      - *view
      - *create
      - *modify
      - *delete
  -
    roles:
      - Member
    grants:
      -
        <<: *view
        mask:
          - secretDesire

• features:
  • Premium grants:

  • resources: ['Bear'] grants:

    roles:
      - Owner Admin
    grants:
      - *view
      - *create
      - *modify
      - *delete

    • roles:
      • Member grants:
      • <<: *view mask:
        • secretDesire