Merge pull request #186 from Oltho/feat-specs-oas

feat: JSON schema for Access Evaluation Request/Response
openid · Jan 7, 2025 · 096b5a9 · 096b5a9
2 parents b41f186 + 3bd3725
commit 096b5a9
Show file tree

Hide file tree

Showing 2 changed files with 171 additions and 0 deletions.
diff --git a/api/schemas/evaluation-request.schema.json b/api/schemas/evaluation-request.schema.json
@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "authzen-evaluation-request",
+  "title": "Access Evaluation API Response",
+  "$comment": "https://openid.net/specs/authorization-api-1_0-01.html#name-the-access-evaluation-api-r",
+  "type": "object",
+  "required": [
+    "subject",
+    "resource",
+    "action"
+  ],
+  "properties": {
+    "subject": {
+      "description": "A Subject is the user or robotic principal about whom the Authorization API is being invoked. The Subject may be requesting access at the time the Authorization API is invoked.",
+      "$comment": "https://openid.net/specs/authorization-api-1_0-01.html#name-subject",
+      "type": "object",
+      "required": [
+        "type",
+        "id"
+      ],
+      "properties": {
+        "type": {
+          "description": "A string value that specifies the type of the Subject.",
+          "type": "string"
+        },
+        "id": {
+          "description": "A string value containing the unique identifier of the Subject, scoped to the type.",
+          "type": "string"
+        },
+        "properties": {
+          "description": "A JSON object containing any number of key-value pairs, which can be used to express additional properties of a Subject.",
+          "type": "object",
+          "example": [
+            {
+              "department": "Sales"
+            },
+            {
+              "department": "Sales",
+              "ip_address": "172.217.22.14"
+            },
+            {
+              "department": "Sales",
+              "ip_address": "172.217.22.14",
+              "device_id": "8:65:ee:17:7e:0b"
+            }
+          ]
+        }
+      }
+    },
+    "resource": {
+      "description": "A Resource is the target of an access request.",
+      "$comment": "https://openid.net/specs/authorization-api-1_0-01.html#name-resource",
+      "type": "object",
+      "required": [
+        "type",
+        "id"
+      ],
+      "properties": {
+        "type": {
+          "description": "A string value that specifies the type of the Resource.",
+          "type": "string"
+        },
+        "id": {
+          "description": "A string value containing the unique identifier of the Resource, scoped to the type.",
+          "type": "string"
+        },
+        "properties": {
+          "description": "A JSON object containing any number of key-value pairs, which can be used to express additional properties of a Resource.",
+          "type": "object",
+          "example": [
+            {
+              "library_record": {
+                "title": "AuthZEN in Action",
+                "isbn": "978-0593383322"
+              }
+            }
+          ]
+        }
+      }
+    },
+    "action": {
+      "description": "A Subject is the user or robotic principal about whom the Authorization API is being invoked. The Subject may be requesting access at the time the Authorization API is invoked.",
+      "$comment": "https://openid.net/specs/authorization-api-1_0-01.html#name-action",
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "description": "The name of the Action.",
+          "type": "string"
+        },
+        "properties": {
+          "description": "A JSON object containing any number of key-value pairs, which can be used to express additional properties of an Action.",
+          "type": "object"
+        }
+      }
+    },
+    "context": {
+      "description": "The Context object is a set of attributes that represent environmental or contextual data about the request such as time of day. It is a JSON ([RFC8259]) object.",
+      "$comment": "https://openid.net/specs/authorization-api-1_0-01.html#name-context",
+      "type": "object",
+      "example": [
+        {
+          "time": "1985-10-26T01:22-07:00"
+        }
+      ]
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "subject": {
+        "type": "user",
+        "id": "[email protected]"
+      },
+      "resource": {
+        "type": "account",
+        "id": "123"
+      },
+      "action": {
+        "name": "can_read",
+        "properties": {
+          "method": "GET"
+        }
+      },
+      "context": {
+        "time": "1985-10-26T01:22-07:00"
+      }
+    }
+  ]
+}
diff --git a/api/schemas/evaluation-response.schema.json b/api/schemas/evaluation-response.schema.json
@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "authzen-evaluation-request",
+  "title": "Access Evaluation API Request",
+  "$comment": "https://openid.net/specs/authorization-api-1_0-01.html#name-the-access-evaluation-api-re",
+  "type": "object",
+  "required": [
+    "decision"
+  ],
+  "properties": {
+    "decision": {
+      "description": "A boolean value that specifies whether the Decision is to allow or deny the operation.",
+      "$comment": "https://openid.net/specs/authorization-api-1_0-01.html#name-access-evaluation-decision",
+      "type": "boolean"
+    },
+    "context": {
+      "$comment": "https://openid.net/specs/authorization-api-1_0-01.html#name-access-evaluation-decision",
+      "type": "object",
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "description": "A string value that specifies the reason within the scope of a particular response.",
+          "type": "string"
+        },
+        "reason_admin": {
+          "description": "The reason, which MUST NOT be shared with the user, but useful for administrative purposes that indicates why the access was denied.",
+          "type": "object"
+        },
+        "reason_user": {
+          "description": "The reason, which MAY be shared with the user that indicates why the access was denied.",
+          "type": "object"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}