Skip to content

Authorization

Claim structure

When converted to an NPL claims object, the contents of a claim are always interpreted as a set of strings values, including the standard JWT reserved claims. Primitives that are not strings will be stringified, and empty claims will be removed.

All array nestings will be flattened, which means that the nesting of arrays does not have any significance and should not convey any information.

Note

The custom properties of the JWT are typically defined in the authorization context of the enterprise that is issuing it. Therefore, NPL derives claims from the existing structure rather imposing a specific schema on the JWT.

Warning

=> is a reserved character sequence and must never be used as part of a claim key or value in the JWT.

Protocol parties

Parties are the ultimate arbiters of how protocol instances and protocol data are used. Every NPL protocol instance requires the binding of party values, a step referred to as 'party assignment'. Assignments are made at the time of protocol instantiation.

An NPL party assignment consists of two sets of key/value pairs, called claims.

  • A set of entity claims (representing a responsible stable entity) . Entity claims can only be changed within the NPL language, with explicit NPL modeling.

  • A set of access claims (for access control). Access claims may be changed unilaterally by the controlling entity (via the engine API).

Each claim in either set may consist of one or more claim values.

Below is an example of what a party assignment may look like. For the moment all claims are optional. However, the iss claim in the entity will become mandatory when the multi node engine is involved.

Determining authorization

Entity claims describe identity or the right to represent a given party or parties. Entity claims are required.

The party can represent its entity but in order to limit the scope of representation, we use and additional set of claims called access claims.

Access claims specify what actions the party can take on the part of the Entity - they are not required. For example, A person has complete autonomy over themselves. Access claims are a form of Attribute Based Access Control (ABAC) and exist on top of entity claims.

How does authorization work?

Authorization ascertains the actual access rights. As explained above, requests for which the token's entity does not match are always rejected. If the entity in the token matches the party assignment's entity, authorization is decided based on the party assignment's access.

Authorization also uses the claims in the token. Specifically, for each of the claims in the party assignment, there must be a matching claim with the correct value in the token.

For a more technical overview of how claims are evaluated, see Claims Evaluation.

Examples

A party assignment limiting access to one specific user

It is possible to authorize only a specific user through a user-specific claim.

Single user claims :

{
  "entity": {
    "iss": ["http://www.noumenadigital.com"],
    "org": ["Noumena Digital AG"]
  },
  "access": {
    "preferred_username": "Bill"
  }
}

An entity-only authorization

{
  "entity": {
    "iss": ["http://www.noumenadigital.com"],
    "org": ["Noumena Digital AG"]
  },
  "access": {}
}

Note that this is an example of the most basic authorization check, which uses no additional claims and relies only on very generic set of claims for its entity. While valid, this is generally not recommended.