Using the Authorizer

After configuration and deployment, the Authorizer can be used to run jobs and consume the output access files. In this section you can find details on the different Modes of executions, Authorizer APIs, Scheduler details, and more.

Authorizer API Endpoints

The following API endpoints are exposed by the Authorizer to execute jobs and manage processes:

Job Execution API

The jobs can be triggered via the Jobs API, or based on a cron schedule in the configuration. For more information, see the Scheduled Job Execution section.

PUT http://{{authz-host}}:8080/1.0/jobs/{{job_name}}

Returns:

• HTTP 200 Success - Job was successfully triggered
• HTTP 409 Conflict - Job with same name is already running. The request is rejected with an error message, prevents multiple instances of the same job from running simultaneously.

Example:

# Start a job
curl -X PUT http://localhost:8080/1.0/jobs/job1 \
  -H 'Content-Type: application/json' \
  -d '{"running": true}'

Job Force Execution API

The API endpoint supports optional force query parameter which allows you to execute a job even if it is already running. This terminates the existing job run and starts a new one.

This is useful if you need to:

• Restart a stuck job
• Override current execution with different parameters
• Start an urgent run regardless of current state

PUT http://{{authz-host}}:8080/1.0/jobs/{{job_name}}?force=true

Example:

# Force start a job (even if one is already running)
curl -X PUT 'http://localhost:8080/1.0/jobs/job1?force=true' \
  -H 'Content-Type: application/json' \
  -d '{"running": true}'

Job Execution History API

"This API endpoint retrieves the execution history of jobs, providing detailed status information for management and tracking purposes. It also supports filtering by run ID." GET http://{{authz-host}}:8080/1.0/jobs/{{job_name}}/history

Examples:

# Get all history for a job
curl http://localhost:8080/1.0/jobs/job1/history

# Filter by specific run ID
curl http://localhost:8080/1.0/jobs/job1/history?filter[run_id]=ba47244d-75dc-4ad6-8bd0-c91f395ff907

Response example:

{
  "data": [
    {
      "job_id": "jb1",
      "run_id": "ba47244d-75dc-4ad6-8bd0-c91f395ff907",
      "status": "SUCCESS",
      "mode": "Normal",
      "success_flows": ["flow1"],
      "success_row_count": 18,
      "start_time": "2024-12-24T13:22:03.988281+02:00",
      "end_time": "2024-12-24T13:22:47.070309+02:00"
    }
  ]
}

Notes:

• Possible statuses - SUCCESS, RUNNING, and FAILED
• Timestamps are in UTC.
• The history data is stored and fetched from the operational database. You may need to maintain this database table and maintain it over time to avoid storing long history and large amount of data.

Template Validation API

The Authorizer generates output files based on Authorization Decisions stored in the operational database and Go Templates that define the file structure and data conversion. To simplify the process of defining Go Templates, the Authorizer exposes a template validation endpoint, allowing users to test template definitions with a sample PDP authorization decision.

This endpoint supports:

• Pre-deployment template testing
• Inline Templates and configured converter reference support
• Template syntax and execution validation

POST http://{{authz-host}}:8080/1.0/templates/validation

The endpoint receives a payload with two parameters:

• template - An inline escaped Go template string
• converterId(alternative to Template) - A reference to a configured converter
• inputs - A JSON array with a sample PDP response simulating the Authorization decision which is processed during flow execution based on PDP definitions.

The endpoint returns template validation errors or a sample of the generated file based on the provided inputs when validation succeeds.

Example with inline template:

curl -X POST http://localhost:8080/1.0/templates/validation \
  -H 'Content-Type: application/json' \
  -d '{
    "template": "{\"groups\":[{{- range $i, $data := . }}{{- if $i }},{{end}}{\"groupName\":\"{{ $data.asset.path }}\"}{{- end}}]}",
    "inputs": [
      {
        "asset": {
          "path": "GroupName12",
          "attributes": {
            "Platforms": ["Platform"]
          }
        }
      }
    ]
  }'

Example with converter reference:

curl -X POST http://localhost:8080/1.0/templates/validation \
  -H 'Content-Type: application/json' \
  -d '{
    "converterId": "t1",
    "inputs": [
      {
        "asset": {
          "path": "GroupName12",
          "attributes": {
            "Platforms": ["Platform"]
          }
        }
      }
    ]
  }'

Modes of Execution

Each Flow can be configured to run in one of two modes: Full or Normal.

Normal Mode (default)

• Performs delta detection by calculating and comparing hashes of all subject attributes fetched from the data source, efficiently processing only subjects that have changed since the last run.
• Ideal for regular incremental updates.

Full Mode

• Executes a complete run, processing all subjects fetched from the data source, regardless of changes in the subject's attributes or their previous state.
• Recommended when:
  • The population size is manageable within the required time constraints
  • System-wide policy changes necessitate a recalculation of all access
  • Full synchronization of access rights is required

Mode Configuration Hierarchy

The execution mode can be specified at different levels, with each level overriding the previous one:

1. Flow Level (Base configuration)

   flows:
     flow1:
       mode: Normal
   

2. Job Level (Overrides Flow mode)

   jobs:
     job1:
       mode: Full
       flows:
         - flow1
   

3. API Level (Overrides both job and flow modes)

   curl -X PUT http://localhost:8080/1.0/jobs/job1 \
     -H 'Content-Type: application/json' \
     -d '{"running": true, "mode": "Full"}' // Or "Normal"
   

This hierarchical configuration provides granular control over execution modes, allowing you to:

• Set default modes at the Flow level
• Override multiple Flow modes at the job level
• Use different modes via APIs without modifying configuration

Example configurations:

flows:
  flow1:
    mode: Normal # Default to incremental updates
  flow2:
    mode: Full # Always do full processing

jobs:
  daily_job:
    mode: Normal # Override both flows to Normal mode
    flows:
      - flow1
      - flow2
  weekly_sync:
    mode: Full # Override both flows to Full mode
    flows:
      - flow1
      - flow2

Scheduled Job Execution

The Authorizer uses Redis for reliable job scheduling and execution. The schedule parameter is used to specify the cron schedule for the job.

You can get more info on cron scheduling expressions from the web in sites such as https://crontab.guru/ or https://crontab.cronhub.io/

Here are some job scheduling configuration examples:

jobs:
  # Daily job at 6 PM
  daily_job:
    flows:
      - flow1
    maxWorkers: 100
    schedule: "00 18 * * *"

  # Weekly job on Monday at 2 AM
  weekly_sync:
    flows:
      - flow1
      - flow2
    maxWorkers: 50
    schedule: "00 02 * * 1"

  # Every 15 minutes
  frequent_check:
    flows:
      - flow3
    maxWorkers: 20
    schedule: "*/15 * * * *"

  # Multiple times per day
  multi_daily:
    flows:
      - flow1
    maxWorkers: 30
    schedule: "00 */4 * * *" # Every 4 hours