Authorization

The authorization resource in Big ACL’s API serves as the Policy Decision Point (PDP), responsible for evaluating requests and returning access decisions (e.g., “allow” or “deny”) based on defined policies and user entitlements. This resource adheres to OpenID AuthZen and its Authorization API 1.0 specification, which outlines the format of authorization requests and responses.

Request Structure

Below is a general structure of a request sent to the authorization resource. This follows the guidelines from the OpenID Authorization API 1.0 specification:

POST /authorization
Authorization: Bearer <token>
Content-Type: application/json

{
  "subject": {
    "id": "user-123",
    "type": "user"
  },
  "resource": {
    "id": "doc-456",
    "type": "document"
  },
  "action": "read",
  "context": {
    "ipAddress": "192.168.1.10",
    "timeOfDay": "2025-03-05T12:34:56Z"
  }
}

Request Fields

• subject: Describes the entity requesting authorization.

  • id: Unique identifier for the subject (e.g., a user ID).

  • type: Type of the subject (e.g., “user”, “service_account”).

• resource: The entity the subject wants to access.

  • id: Unique identifier for the resource (e.g., a document ID).

  • type: Classification of the resource (e.g., “document”, “record”, “dataset”).

• action: A string identifying the intended operation (e.g., “read”, “write”, “delete”).

• context (optional): A set of key/value attributes that may influence the decision (e.g., time, location, IP address, environment information).

All fields conform to the OpenID AuthZen specification for PDP requests. Additional properties may be included if required by your organization’s policies; the PDP will ignore unrecognized fields that are not relevant to the decision.

Response Structure

The authorization resource returns a JSON object indicating whether the requested action is allowed or denied, possibly with additional metadata.

Example Response

{
  "decision": "allow",
  "timestamp": "2025-03-05T12:34:57Z",
  "policyId": "policy-789",
  "reasons": [
    "User is assigned to role:editor",
    "Document security classification is Public"
  ]
}

Response Fields

• decision: Indicates the outcome of the evaluation. Common values include:

  • allow: The subject is permitted to perform the requested action on the resource.

  • deny: The subject is forbidden from performing the requested action.

• timestamp: Server-side timestamp (ISO 8601) at the moment the decision was made.

• policyId (optional): Identifies the policy or set of policies used to reach the decision.

• reasons (optional): A list of human-readable statements indicating why the decision was made. This is especially useful for auditing or debugging.

Error Handling

If the PDP cannot evaluate the request—such as missing credentials, invalid payload format, or server errors—it will return an appropriate HTTP status code and error structure. For example:

{
  "error": "invalid_request",
  "error_description": "Missing 'subject.id' in the request body"
}

Possible error codes include:

• 400 Bad Request: The request was malformed (e.g., missing required fields).

• 401 Unauthorized: The API Key is missing or invalid.

• 403 Forbidden: The request cannot be evaluated or is explicitly forbidden.

• 500 Internal Server Error: An unexpected server-side issue occurred.