[ADR] Client credentials token custom claims conventions

[JakubC-projects]

Context

For many of our APIs additional information about a client is required in order to implement proper access control.

The information that is needed to add is the "organizational scope" of the client, meaning the org for which the client may fetch data.

For example in the Core API, an organization can fetch personal data only for persons that have either consented to sharing data or that are affiliated with the organization.

To facilitate this sort of logic we need a way to link a client credentials access token to an organization.

It turns out that often a single auth0 client is used in context of multiple organizations, so it's useful to be able to link multiple organizations to one auth0 client.

Additionally, some applications (global applications) are not limited to any set of organizations and can access all data available in the API.

Decision

Two custom claims are going to be added for each application that needs to use one our APIs.

1. global - contains a boolean value, signifying whether an application is global or not, the claim may be missing, in which case a non-global application should be assumed
2. org_uids - contains an array of uuids, referencing the uid field of an org in the Core API. The API should only return data that is available in the context of those organizations. Ignore if global is true. If the claim is missing, assume empty array.

Consequences

All APIs that deal with data is restricted depending on the organization accessing it, will need to properly interpret those claims and use it for access control

Alternatives

Additional ways of encoding the same information were considered:

1. Having additional org_ids claim containing the associated orgID values. It was not chosen because of difficulty in maintaining two claims that contain basically the same information
2. Using a special value of org_uids claim instead of the global claim. It was not chosen because it seemed to implicit for such important information
3. Expressing the org_uids as a comma delimited string, instead of json array. It was not chosen because there is more standard tooling around parsing json, than other more custom encodings