Overview
Field implementations in the Ed-Fi ecosystem have come across the need for record-level ownership in the Ed-Fi ODS / API. These needs seem to stem from authorization use cases important in local contexts. As the Ed-Fi ODS / API primarily uses a relationship-based authorization strategy based on education organizations, there is sometimes a lack of the granularity necessary to meet all desired use cases.
Record level ownership has been proposed by the Arizona DOE as a general purpose solution to this situation. An initial proposed design was surfaced to the Technical Advisory Group for consideration (see February 2019 meeting notes and the attached deck). The proposal is framed as a set of optional elements to the Ed-Fi ODS / API (i.e. they could be turned off if not needed).
Ed-Fi Alliance also held a Record Level Ownership in the Ed-Fi ODS SIG to discuss this further. The following design recommendation is largely describes the work the SIG produced.
Overall Design
Each aggregate root entity in the ODS will be assigned with an ownership token indicating the access rights to that resource. Record Level Ownership EdFi_Admin database will be modified to hold ownership tokens for the API client. API logic will be modified to populate the new ownership token property on the aggregate root entity from the API client's key context. This could probably be done in the Create method of the CreateEntity<T> class. ODS / API authorization layer design will be expanded to support multiple authorization strategies for a give resource/action combination. This really is an authorization concern and while the flexibility of the general IoC-based architecture would allow the functionality to be configured in as additional C# classes driven by a feature configuration value, the most natural place for it to land is in the authorization code driven by authorization metadata. Authorization metadata in Record Level Ownership EdFi_Security database would need schema changes to support multiple authorization strategies. Authorization code would need to be updated to identify multiple matching authorization strategies for a request, and apply multiple sets of filter criteria to the queries. Sandbox and On-prem admin Apps and security visualization tool would need to be updated.
| Anchor | ||||
|---|---|---|---|---|
|
EdFi_Admin Database Changes
In order to authorize individual resource items in the API based on the concept of "ownership", each API client will need to have an associated "Ownership Token" that is captured with each resource the client creates. The API client's claims information will then need to include a list of "Ownership Tokens" that can be used to identify which resource items they currently "own", and the authorization process will filter results and access against this list against based on the target resource's "Ownership Token" value.
...
Create a new OwnershipTokens table, to capture the ownership tokens that are being used to create records in the ODS, as follows:
Column Name
Data Type
Allow Nulls
OwnershipTokenId smallint IDENTITY No A description column could also be added for display purposes for UI-based administration, perhaps being defaulted to the associated Application's name and a creation date/time (or similar).
Modify the ApiClients table, adding the following column (and associated foreign key constraint) to capture the ownership token associated with the API client for creation:
Column Name
Data Type
Allow Nulls
OwnershipToken_OwnershipTokenId smallint (FK) Yes Since this table represents the usage of a particular ownership token by an API client when creating resource items, a unique constraint should also be added to the column to prevent a token from being inadvertently being assigned to another API client.
Create a new ApiClientOwnershipTokens table, to capture the tokens currently "owned" by the API client (allowing the client to modify the associated resource items), as follows:
Column Name
Data Type
Allow Nulls
ApiClientOwnershipTokenId int IDENTITY No ApiClient_ApiClientId int (FK) No OwnershipToken_OwnershipTokenId smallint (FK) No If an "Ownership Token" should only be associated with 1 API client at a time, a unique constraint should be added to the OwnershipToken_OwnershipTokenId column.
| Anchor | ||||
|---|---|---|---|---|
|
EdFi_Ods Database Changes
Every aggregate root table in the ODS should have an additional "boilerplate" column added to capture the "Ownership Token" of the API client that created the record. The suggestion is to create these columns as CreatedByOwnershipTokenId of type smallint, and made nullable.
| Anchor | ||||
|---|---|---|---|---|
|
EdFi_Security Database Changes
The application of an "ownership-based" authorization strategy should be done in an additive fashion. To facilitate this, we will need to be able to define multiple authorization strategies for the default resource claim/action "tuples" (in the ResourceClaimAuthorizationMetadatas table), as well as for claim set-specific overrides (in the ClaimSetResourceClaims table). The current design of these tables are shown below.
...