User authentication and authorization

Datahub documentation home

The data hub treats authentication and authorization as two separate concepts.

• Authentication checks that the user is who they say they are.
• Authorization checks that the user is allowed to do what they have requested.

Authentication and authorization are controlled by plug-in classes within the properties file.

The authenticator property identifies the class to use to authenticate the user. This can be one of:

• AllowAllAuthenticator - allow any access. This is intended for testing.
• BasicAuthenticator - perform authentication using HTTP authorization header and Basic authorization
• JWTAuthenticator - perform authentication using HTTP authorization header passing a JSON web token (JWT) as a bearer token.

The authorizer property identifies the class to use to authorize calls. This can be one of:

• AllowAllAuthorizer - allow any access. This is required for batch access.
  
• BasicAuthorizer - check authority against an authority file.
  

Authentication is applied when a user is directly making a request, i.e. through the web services interface, and a new authenticator is created for each request.

Authorization is applied more deeply in the message receipt and message processing. An authorizer is associated with the instance context.

Basic authentication

In basic authentication, the request carries a header with a user name and password. The data hub only support pre-emptive authentication, in which the user name and password are passed on the first call.

The basic authentication is checked against a file of users. The file is identified by the users propery within the properties file. This is evaluated relative to the location of the property file, and defaults to "users.json" in the same folder as the properties file.

The users file is a simple JSON file with the following format:

{
  "userId1":"saltHash1",
  "userId2":"saltHash2",
  ...
}

The saltHash is a string that contains a random salt value and a secure hash of the password with the salt value.

You can calculate a saltHash for a password using the HashPassword utility.

java -cp datahub-dist.jar com.metrici.datahub.HashPassword password

Manually copy the returned value into the users.json file for that user.

Use a verbosity greater than 2 to log more details if users fail authentication.

JWT authentication

In JWT authentication, the request passes a JSON web token (JWT) as a Bearer token in an authorization header.

The JWT is verified against a public key held in a file in PEM format. The public key is identified by the publicKey property within the properties file. This is evaluated relative to the location of the property file, and defaults to "public_key.pem" in the same folder as the properties file.

If the JWT passes verification, the user is read from the "sub" claim in the JWT payload. Because the JWT is only used for authentication none of the other claims are checked.

The clock skew (maximum allowable difference in timestamps for checking JWT expiry times) defaults to 60 seconds. This can be changed by setting the clockSkew property to something other than 60.

Basic authorization

Basic authorization reads authorization information from an authority.json file, identified by the authority property. It defaults to authority.json in the same folder as the properties file.

The authority file has the following format.

{
  "groups": {
    "groupId": ["userId1", "userId2", ... ],
    ...
  },
  "permissions": [
    {
      "action": ["get", "put", "refresh" ],
      "user": ["groupId", "userId", ... ],
      "system": "system",
      "entity": ["entity1", "entity2", ...]
    },
    ...
  ]
}

The groups section defines groups, which are simply lists of user ids.

The permissions section list multiple permission statements.

Each permission statement:

• Permits one or more of the actions: get, put, refresh or execute. Note that refresh permission does not imply put permission. If there is one action, it can be coded as a single string, not in an array. An action of "*" can be used to permit any action.
  
• Grant to one or more users or groups, either an array or a single string. Use a user of "*" to permit all authenticated users.
  
• Optionally for a source system. System defaults to the default system. Granting read permissions on non-default entities is not currently supported, but is reserved.
  
• To one or more entities, either as an array or a single string. Use an entity of "*" to permit the action on any entity.

The wildcard "*" can only be used for action, user and entity. For system it indicates the default system, not any source system.

Here is a simple example.

{
  "groups": {
    "readUsers": ["bill", "jane", "amy"],
    "adminUsers": ["mary"]
  },
  "permissions": [
    {
      "action": ["put","refresh"],
      "user": ["sales_system"],
      "system": "sales",
      "entity": ["product","sale"]
    },
    {
      "action": "get",
      "user": ["readUsers","adminUsers"],
      "entity": ["product","sale"]
    },
    {
      "action": "get",
      "user": ["adminUsers"],
      "entity": "*"
    }
  ]
}

This permits the "sales_system" user (an API user) to update or refresh the product or sale entities from the sales system. Note that they must be given "update" even if they have "refresh" permission also.

readUsers (bill, jane and amy) can all read the product and sale entities. The adminUsers (just mary) can read any entities.

Note that permit, user and entity can be arrays or a single value, but system is always a single value.

Use a user of "null" (not null) to indicate authorization for the null user. This may be required for post-processing which runs without a user authority. Assuming you are using an authenticator, all real users will be authenticated as they call the data hub, and "null" can be used to indicate the system itself.

Use a verbosity greater than 2 to log more details if users are not authorized, and a verbosity greater than 3 to log the authorization details when the file is read.