O-MI Authorization Service

Standalone server that implements O-MI Node reference implementation authorization protocol v2. This service needs one form of authentication that should be configured in some other service.

Features

• Model: Permissions <-> Role/Group <-> Consumer
  • (Consumer can belong to many groups, groups can have many permission rules)
  • Permissions can be set to O-MI write, read, delete and call requests separately
  • Allow and deny permissions can be set to any O-DF path to affect it and its children nodes.
  • Deny permissions overrides allow permissions (also on the children nodes of allow rules)
  • Permission calculation in set operations:
    1. Combine groups: <allow-a> union <allow-b>, <deny-a> intersect <deny-b> (exception: a intersect {} = a)
    2. In O-MI Node: <request-O-DF> intersect <allow> difference <deny>
• Automatic DEFAULT group to set default permissions for all users (and those without user account if allowed by O-MI Node/authentication service). By default it has no permissions. Also note that in order to intersect deny permissions in DEFAULT, some other group needs to have some different deny permissions instead of an empty set. You can create a deny permission to a non-existing path to achieve "admin" rights.
• Automatic <username>_USERGROUP group for each user to easily set permissions to single user. By default it has no permissions.
• JSON REST API
• Configurable SQL database

Configuration

O-MI Node

1. For now you need to compile O-MI Node from feature_authapiv2 branch in O-MI Node (It will be released in near-future release).
2. In application.conf, set omi-service.authAPI.v2.authorization-url to and parameter object as below:

# This example is at root level, outside of any objects
omi-service.authAPI.v2 {
    enable = true

    # Url to do authentication (checking if the consumer have valid credentials or session)
    #authentication.url = "<set for authentication>"
    

    # Url to do authorization (checking what data a given user has permissions to read or write)
    authorization.url = "http://localhost:8001/v1/get-permissions"
    authorization.method = "POST"
    
    # predefined variables: requestType and requestTypeLetter which tell O-MI verb name (read, write, call, delete)
    # for O-MI Authorization ref. impl: http POST {"username": <username>, "request": <first-character-of-omi-request-type>}
    parameters.toAuthorization {
      # authorizationHeader {}
      # headers {}
      jsonbody {
        # jsonproperty = variableName
        username = "username"
        request = "requestTypeChar"
        # Uncomment to include additional groups/roles for the user (for this request only) from "roles" variable
        #groups = "roles"
      }
    }

    ## Uncomment these to make read requests to work without user (logging in) and get default permissions from authorization module:
    ## we can skip authentication (othewise it will fail which will result in unauthorized error)
    #parameters.skipAuthenticationOnEmpty = ["token"]
    ## and send empty username to authorization (authorization module supports sending of default permissions for empty username)
    #parameters.initial {
    #  username = "" # to send empty username if username is not given by authentication
    #}
}

Authorization module

See configuration file application.conf:

• in release package: conf/application.conf
• in development (create if missing): src/main/resources/application.conf
• defaults

Running

1. Download release
2. Run startup script
   • Linux/Mac: ./bin/o-mi-authorization
   • Windows: ./bin/o-mi-authorization.bat

Compiling

1. Install sbt
2. run or package
   • Run: sbt run
   • Package: sbt universal:packageBin (zip) or sbt universal:packageZipTarball (tar)

API docs

• Html API docs
• swagger.yaml
• Example commandline usage

Debugging

Uncomment all loggers in logback.xml, which is in directory src/main/resources/ in dev version and in conf/ in releases.

Acknowledgements

Sections of this project has been developed as part of the bIoTope Project, which has received funding from the European Union’s Horizon 2020 Research and Innovation Programme under grant agreement No. 688203.