Security & ACL Management

Joynare Nexus provides an enterprise-grade Role-Based Access Control (RBAC) system. This system allows you to manage users, groups, and Access Control Lists (ACLs) to secure your flow services.

The Security Model

Joynare Nexus uses a three-tier security model:

1. Users: Individual identities that authenticate with the system.
2. Groups: Collections of users. A user can belong to multiple groups.
3. ACLs (Access Control Lists): Permissions that allow access to specific resources. A group can be assigned multiple ACLs.

ACL Inheritance (GitOps)

Access control for flows is managed via inheritance. This allows you to set security policies at a high level (e.g., a namespace) and have them automatically apply to all child services.

Folder Metadata (_folder.yaml)

To set an ACL for an entire directory and its children, create a _folder.yaml file in that directory:

acl: "finance-department"

Any flow within this directory (or its subdirectories) will inherit the finance-department ACL unless it specifies its own override.

Flow Override

You can explicitly set an ACL for a specific flow in its flow.yaml:

name: "TransferFunds"
namespace: "finance"
acl: "super-secure-acl"
steps:
  - type: "invoke"
    service: "system.utils:Log"
    input:
      level: "INFO"
      message: "Access Granted"

Effective ACL Calculation

1. Explicit Override: If a flow.yaml defines an acl, that value is used.
2. Parent Inheritance: If not, the system searches upwards through parent directories for the nearest _folder.yaml with an acl defined.
3. System Default: If no ACL is found in the hierarchy, the flow defaults to the default ACL.

System Configuration (system.yaml)

The security database is configured in config/system.yaml. This file is reserved for internal ESB infrastructure and is separate from the connections.yaml used by developers for their business flows.

Example config/system.yaml:

database:
  driver: "mysql"
  dsn: "root@tcp(localhost:3307)/joynare_nexus?parseTime=true"

Emergency Fallback Credentials

The auth section in your route configurations (e.g., routes/server.yaml) defines the authentication requirement. While Joynare Nexus checks the database first, you can define fallback credentials for emergency bootstrap situations.

Best Practice: Never hardcode credentials. Use environment variables as shown below:

# routes/server.yaml
autoExpose:
  auth:
    type: basic
    username: "${NEXUS_ADMIN_USER}"
    password: "${NEXUS_ADMIN_PASSWORD}"

Encryption in Transit (TLS/HTTPS)

Joynare Nexus supports industry-standard TLS encryption to secure data as it travels between clients and the ESB. You can configure multiple HTTPS listeners alongside standard HTTP listeners.

Configuration

To enable HTTPS, you must provide a valid certificate and private key in the listeners section of routes/server.yaml:

server:
  host: "0.0.0.0"
  listeners:
    - port: 443
      protocol: "https"
      certFile: "/path/to/server.crt"
      keyFile: "/path/to/server.key"

Key Features

• Dual Mode: Run HTTP and HTTPS simultaneously on different ports.
• Dynamic Management: Future support for managing certificates via the Administration UI.
• Strong Ciphers: Built on Go's robust crypto/tls package, supporting modern TLS 1.2 and 1.3 protocols.

---

Database Management (MySQL)

While resource-to-ACL mapping is managed via GitOps, the User-to-Group-to-ACL relationships are stored in this internal MySQL database. This allows for dynamic management via the Administration UI without restarting the ESB.

Initializing the Security Database

To set up the security tables and seed the initial admin user, run:

joynare-nexus security init-db

This command will:

1. Create the database (if defined in system.yaml).
2. Create the necessary tables (users, groups, acls, etc.).
3. Create a default admin user with password admin123.
4. Create a default ACL and link it to the admin group.

Design & Admin API Security

While flow execution endpoints on the standard listeners (9090 / 9091) are governed by the database-backed RBAC and ACL system, the secure Design and Admin API listener (9092) is isolated and uses an API Key security mechanism.

Key Authentication Configuration

Specify an optional apikey configuration under the designApi field in routes/server.yaml:

server:
  designApi:
    enabled: true
    port: 9092
    apikey: "your-secret-api-key"

• When configured: all non-preflight requests (GET, POST, PUT, DELETE) to /api/design/* and /api/admin/* must carry the X-API-Key HTTP header containing the exact configured value. Otherwise, they are rejected with 401 Unauthorized.
• When omitted/blank (default): the Design and Admin APIs permit fully unauthenticated access, enabling a friction-free development experience locally.
• CORS Preflight: Browsers dispatching preflight OPTIONS requests receive a successful 200 OK with allowed CORS headers (X-API-Key, Content-Type) automatically without requiring a key, avoiding browser CORS blocks.

Verification

You can verify the effective ACL for any flow using the validate command:

joynare-nexus validate my-namespace:my-flow

The output will display both the explicitly defined ACL and the calculated Effective ACL.