ActiveDebianSync Cluster OAuth

• Back to the ActiveDebianSync main section

How to configure OAuth 2.0 authentication for cluster replication in ActiveDebianSync.
Cluster replication supports Token Authentication (default) with a shared secret token configured on all nodes
or OAuth 2.0 Authentication when Client credentials flow using an external OAuth provider

Configuration via Web Console

• Navigate to Cluster > Replication
• Click Configure in the OAuth Settings card
• Select OAuth 2.0 from the Authentication Mode dropdown
• Fill in the OAuth configuration:
     - Enable OAuth: Check to enable OAuth authentication
     - Token URL: Your OAuth provider's token endpoint
     - Client ID: The client ID for this node
     - Client Secret: The client secret (stored securely)
     - Scopes: OAuth scopes (default: `cluster:sync`)
• Click Save

Manual configuration

edit config.json with

{
    "cluster_enabled": true,
    "cluster_node_name": "node1",
    "cluster_port": 9191,
    "cluster_auth_mode": "oauth",
    "cluster_oauth_enabled": true,
    "cluster_oauth_client_id": "activedebiansync-node1",
    "cluster_oauth_secret": "your-client-secret",
    "cluster_oauth_token_url": "https://auth.example.com/oauth/token",
    "cluster_oauth_scopes": "cluster:sync",
    "cluster_peers": [
        {
            "name": "node2",
            "address": "192.168.1.101:9191",
            "enabled": true
        }
    ]
}

OAuth Provider Setup

Your OAuth provider must support the Client Credentials Grant (RFC 6749 Section 4.4).

Example: Keycloak

1. Create a new client in your Keycloak realm
2. Set Client Protocol to openid-connect
3. Set Access Type to confidential
4. Enable Service Accounts Enabled
5. Configure the token URL: https://keycloak.example.com/realms/{realm}/protocol/openid-connect/token

Example: Auth0

1. Create a new Machine-to-Machine application
2. Authorize the application for your API
3. Use the token URL: https://{tenant}.auth0.com/oauth/token

Example: Azure AD

1. Register an application in Azure AD
2. Create a client secret
3. Use the token URL: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token

Token Validation

When a node receives a connection with OAuth authentication:

1. The receiving node acquires its own OAuth token using the same credentials
2. Tokens are compared - if they match, authentication succeeds
3. If tokens differ (due to timing), basic format validation is performed
4. For production environments, consider implementing token introspection

Cluster Setup with OAuth

All Nodes Same Credentials

The simplest setup is to use the same OAuth client credentials on all nodes:

Node 1: client_id=cluster-sync, client_secret=shared-secret
Node 2: client_id=cluster-sync, client_secret=shared-secret
Node 3: client_id=cluster-sync, client_secret=shared-secret

This ensures all nodes receive the same access token and can authenticate with each other.

Per-Node Credentials

For enhanced security, each node can have unique credentials:

Node 1: client_id=node1-sync, client_secret=secret1
Node 2: client_id=node2-sync, client_secret=secret2
Node 3: client_id=node3-sync, client_secret=secret3

This requires implementing token introspection at the OAuth provider level for validation.