_Security Visualization Tool

Owned by Ian Christopher (Deactivated)
Last updated: Jul 08, 2019 by Chris Moffatt (Deactivated)
3 min read

Authorization schemes in an Ed-Fi ODS / API implementation are flexible and can be customized to serve a variety of security needs. However, the configuration metadata can be complex, which can make it difficult for administrators to understand exactly what permissions apply for a resource. The Ed-Fi ODS / API solution comes with a command-line Security Visualization Tool to help implementers visualize authorization configurations.

This section outlines how to configure and use the Security Visualization Tool. The high-level steps are:

Each step is outlined in detail below.

Step 1. Install and Configure GraphViz

The security visualization tool requires GraphViz — open source visualization software — to be installed. You can install the latest stable MSI release for Windows here.

Step 2. Build and Run the Security Visualization Tool

  • Start Visual Studio, open the Security Visualization Tool solution from \Ed-Fi-ODS\Utilities\GenerateSecurityGraphs\GenerateSecurityGraphs.sln, and build the solution.
  • Open a Console window and navigate to \Ed-Fi-ODS\Utilities\GenerateSecurityGraphs\GenerateSecurityGraphs\bin\Debug.
  • Run GenerateSecurityGraphs.exe to view the parameters that can be passed to the application.
  • Execute the tool to generate the vizualizations. The example below assumes that you have followed the Ed-Fi ODS / API Getting Started steps successfully.
GenerateSecurityGraphs.exe -o "C:\graphs" -f

Step 3. Review Output

Once the tool has run, you will find a series of visualization files in the output folder you specified. There are .png and .svg versions for each schema. The root of the folder contains visualizations for the set of authorizations that are possible, and there is a sub-folder for each authorization claim set that has been configured. The as-shipped ODS / API v3.1 contains five claim sets, resulting in five folders. 

Example Output

This section provides some examples of output from the Security Visualization Tool, along with explanatory notes. An understanding of the concepts described in /wiki/spaces/ODSAPI32/pages/27100346 is useful to fully understand the visualizations.

Education Organizations

The diagram below shows permissions for accessing education organization entities for the "Ed-Fi Sandbox" claim set, where full Create, Read, Update, and Delete (CRUD) operations are authorized. The diagram also indicates that the authorization strategy associated with the claim is NoFurtherAuthorizationRequired. Note that the shading of cells has relevance. Dark shading indicates that there are explicit claims assigned to a role, while lighter variants of a color indicates that the permissions are inherited.

The diagram below shows permissions for accessing education organization entities for the "SIS Vendor" claim set. In this case, it is assumed that the education agency implementing the Ed-Fi ODS / API will load and manage education organizations, so SIS vendor applications are only granted Read authorization. 

Descriptors

Permissions for accessing Ed-Fi Descriptors are separated into two types: "Managed Descriptors" (managed by API clients), and "System Descriptors" (managed by the system).

The diagram below shows permissions for accessing Managed Descriptors for the "SIS Vendor" claim set. The NamespaceBased authorization strategy is applied to Create, Update, and Delete operations, which ensures that only API clients with the appropriate Namespace prefix can add or change a managed Descriptor, while the NoFurtherAuthorizationRequired strategy is applied to Read operations, meaning that other API clients read a managed Descriptor.

The diagram below shows permissions for accessing System Descriptors for the "SIS Vendor" claim set, where only Read access is allowed.