Authentication and Authorization

The Gateway provides a flexible authentication and authorization system that allows administrators to control who can access the system and what actions they can perform. The system supports three authentication modes and a role-based access control (RBAC) system for fine-grained permissions. Specification

Authentication verifies identity, while Authorization determines permitted actions (permissions).

Authentication methods

The Gateway supports three authentication modes, configured in the auth_config.json file:

1. No authentication (default)

This mode disables authentication entirely. Requests are processed without identity verification. If auth_config.json is not provided, the system defaults to this mode.

Configuration:

{
  "auth": "none"
}

2. Basic authentication

Use case: Simple username/password authentication for most deployments.

In this mode, users authenticate with a username and password. After successful authentication, the server issues a session cookie that the client sends with subsequent requests.

Configuration:

{
  "auth": "basic",
  "policies": [],
  "roles": []
}

Setting up the superuser

When Basic authentication is enabled, an initial superuser account with full administrative privileges should be created. This account can create other users and assign roles.

Option 1: Via environment variable

export GC_HUB_SUPERUSER_PASSWORD="your-secure-password"
./gc_service_hub

Option 2: Via command line

./gc_service_hub --superuser-password "your-secure-password"

The commands above create a user named superuser with the specified password. The superuser has all permissions and can call any endpoint in the REST API.

Session cookies

After successful authentication, the server sets a session-id cookie. Browsers automatically send this cookie with subsequent requests to maintain the session.

API keys

For programmatic access (scripts, automation, CI/CD), API keys can be used instead of session cookies:

1. Authenticate with credentials.
2. Create an API key via the REST API.
3. Include the returned key in the API_KEY header: <your-key>

3. LDAP/Kerberos authentication

This mode integrates with an LDAP directory and uses Kerberos for authentication. Users authenticate using domain credentials, and roles are automatically synchronized from LDAP security groups. The LDAP/Kerberos mode also includes the Basic auth mechanism described above, so LDAP-managed users can create local Basic users and authenticate using those credentials.

Configuration:

{
  "auth": {
    "ldap": {
      "server_fqdn": "ldap.example.com",
      "use_ssl": true,
      "tls_no_verify": false,
      "base_search_dn": "DC=example,DC=com"
    }
  },
  "policies": [],
  "roles": []
}

Configuration options:

• server_fqdn: Fully qualified domain name of the LDAP server (e.g., ldap.example.com)
• use_ssl: Enable TLS/SSL for the LDAP connection
• tls_no_verify: Skip TLS certificate verification

System requirements

krb5 libraries must be installed and properly configured to use LDAP/Kerberos authentication.

Role synchronization from LDAP groups

The Gateway automatically synchronizes user roles from LDAP security groups. Groups must be prefixed with GC_ to be recognized as roles.

Example:

• LDAP Group: GC_Admin → Gateway Role: Admin
• LDAP Group: GC_Viewer → Gateway Role: Viewer
• LDAP Group: Engineering → Ignored (no GC_ prefix)

Role synchronization occurs:

• when a user first authenticates
• periodically every 5 minutes for all managed LDAP users

Important: Roles for LDAP-managed users cannot be modified through the Gateway API. They are controlled exclusively through LDAP group membership.

Authorization (RBAC)

The Gateway uses a Role-Based Access Control (RBAC) system to determine allowed actions for authenticated users. Authorization is configured in auth_config.json.

Core concepts

Resources

A resource is any REST API endpoint, identified by its URL path (without the /api/{version} prefix). Resource patterns support wildcards to match multiple endpoints.

Resource patterns support two wildcards:

• * - Matches exactly one path segment

  • /datapoints/*/values matches /datapoints/temp1/values but NOT /datapoints/temp1/raw/values
  • Can also be used to match the prefix os suffix in a path segment: /users/*suf/roles/pre_* matches /users/sufjohn/roles/preadmin

• ** - Matches zero or more path segments (recursive)

  • /plugins/** matches /plugins/, /plugins/instances, /plugins/instances/start/abc, etc.

Access types

Each resource can grant three types of access, mapped from HTTP methods:

Policies

A policy groups multiple resources and their allowed access types.

Example:

{
  "name": "DATAPOINT_READ",
  "description": "Read access to all datapoints",
  "resources": [
    {
      "resource": "/datapoints/**",
      "access": ["READ"]
    }
  ]
}

Roles

A role bundles multiple policies. Assigning a role to a user grants the permissions from the role’s policies.

Example:

{
  "name": "Operator",
  "policies": ["DATAPOINT_READ", "PLUGIN_CONTROL"]
}

Users

Local users (Basic auth) can be assigned roles through the API. LDAP users receive roles automatically from LDAP group memberships (groups prefixed with GC_).

Flow of authorization

1. A client makes a request to an endpoint (e.g., GET /users).
2. The system determines the required access type based on the HTTP method (GET = READ).
3. The system checks all policies in the user’s roles.
4. The system matches the request path against resource patterns in those policies.
5. If a matching resource grants the required access type, the request proceeds.
6. Otherwise, the request is denied with 403 Forbidden.

Complete example configuration

{
  "auth": "basic",
  "policies": [
    {
      "name": "PLUGIN_ADMIN",
      "description": "Full control over plugin instances",
      "resources": [
        {
          "resource": "/plugins/instances/**",
          "access": ["READ", "WRITE", "EXECUTE"],
          "description": "All plugin instance operations"
        }
      ]
    },
    {
      "name": "DATAPOINT_READ",
      "description": "Read access to datapoints",
      "resources": [
        {
          "resource": "/datapoints/**",
          "access": ["READ"],
          "description": "View all datapoints"
        }
      ]
    },
    {
      "name": "USER_MANAGEMENT",
      "description": "Manage users and roles",
      "resources": [
        {
          "resource": "/users/**",
          "access": ["READ", "WRITE", "EXECUTE"],
          "description": "Full user management"
        }
      ]
    }
  ],
  "roles": [
    {
      "name": "Admin",
      "policies": ["PLUGIN_ADMIN", "DATAPOINT_READ", "USER_MANAGEMENT"]
    },
    {
      "name": "Operator",
      "policies": ["PLUGIN_ADMIN", "DATAPOINT_READ"]
    },
    {
      "name": "Viewer",
      "policies": ["DATAPOINT_READ"]
    }
  ]
}

Default behavior

• Unauthenticated requests (with auth: "none") are denied unless explicitly permitted.
• Authenticated users with no roles are denied all access.
• Superuser (Basic auth only) has implicit access to all resources.
• LDAP users receive roles from their GC_-prefixed LDAP groups.

Implementation details

Technical details about authentication are available in the auth submodule.