Security Configuration

The Security section configures how AI agents authenticate with the Synentra gateway, including token issuance, external identity validation, and authentication header behavior.

---

Agent Authentication

The AgentAuth section controls how Synentra receives, validates, and issues authentication tokens.

Property	Type	Default	Description
UseCustomHeader	bool	true	Enables the use of a custom authentication header instead of the standard Authorization header.
CustomHeaderName	string	"Synentra-Authorization"	Name of the custom authentication header.
FallbackToAuthorization	bool	false	When enabled, Synentra also accepts tokens from the standard Authorization: Bearer header.
TokenIssuance	TokenIssuanceConfiguration	{}	Configuration for tokens issued by Synentra.
ExternalIdentity	ExternalIdentityConfiguration	{}	Configuration for validating tokens issued by an external identity provider.

Example:

"Security": {
  "AgentAuth": {
    "UseCustomHeader": true,
    "CustomHeaderName": "Synentra-Authorization",
    "FallbackToAuthorization": false
  }
}

Token Issuance

The TokenIssuance section configures JWT tokens generated by Synentra.

Synentra uses these settings when issuing agent access tokens after successful authentication.

Property	Type	Default	Description
Secret	string	""	Automatically generated in Development
Issuer	string	""	JWT issuer (iss claim).
Audience	string	""	JWT audience (aud claim).
Expiration	TimeSpan	00:15:00	Lifetime of issued tokens.

Secret Configuration

The TokenIssuance.Secret value is handled differently depending on the environment.

Development Environment

In the Development environment, Synentra automatically generates a secure signing secret when no secret is configured.

The generated secret:

• Is created using a cryptographically secure random generator.
• Is persisted locally so that tokens remain valid between application restarts.
• Is reused for subsequent executions.

By default, the secret is stored in:

~/.synentra-agentauth-selfsigned-secret

The default location can be overridden using:

SYNENTRA_SELF_SIGNED_DEV_SECRET_FILE

You can also explicitly provide a development secret using:

SYNENTRA_SELF_SIGNED_SECRET

or:

"Security": {
  "AgentAuth": {
    "TokenIssuance": {
      "Secret": "your-development-secret"
    }
  }
}

Production Environment

In production environments, Synentra requires an explicitly configured signing secret.

The application will fail to start if TokenIssuance.Secret is missing.

Configure the secret using one of the supported secret management mechanisms:

"Security": {
  "AgentAuth": {
    "TokenIssuance": {
      "Secret": "your-production-signing-secret",
      "Issuer": "synentra",
      "Audience": "synentra-agents",
      "Expiration": "00:15:00"
    }
  }
}

For production deployments, it is recommended to load the secret from a secure secret provider instead of storing it in configuration files.

Supported options include:

• Environment variables
• Azure Key Vault
• Container secrets
• Other supported secret management integrations

---

External Identity Provider

The ExternalIdentity section configures authentication using an external identity provider.

This can be used with providers such as:

• Keycloak
• Auth0
• Azure AD / Entra ID
• Custom OpenID Connect providers

Property	Type	Default	Description
Enabled	bool?	false	Enables or disables external identity validation.
Provider	ExternalIdentityProviderType	Jwt	External authentication provider type.
Jwt	JwtIdentityConfiguration	{}	JWT validation configuration.

JWT Identity Configuration

Property	Type	Default	Description
Authority	string	""	OpenID Connect authority URL of the identity provider.
Audience	string	""	Expected JWT audience.
MetadataUrl	string?	""	Optional OpenID Connect metadata endpoint.
ValidateIssuer	bool	false	Enables issuer validation.
ValidateAudience	bool	false	Enables audience validation.

Example using Keycloak:

"Security": {
  "AgentAuth": {
    "ExternalIdentity": {
      "Enabled": true,
      "Provider": "Jwt",
      "Jwt": {
        "Authority": "http://keycloak:8080/realms/synentra",
        "Audience": "synentra-gateway",
        "ValidateIssuer": true,
        "ValidateAudience": true
      }
    }
  }
}

Authentication Flow

The authentication process depends on the configured identity source.

Token Issuance Flow

When using Synentra token issuance:

1. An agent requests a token from Synentra.
2. Synentra validates the agent credentials.
3. Synentra creates a signed JWT using the TokenIssuance configuration.
4. The issued token contains:
   • sub — the agent identifier
   • trust_score — current agent trust score
   • iss — configured issuer
   • aud — configured audience
   • exp — token expiration time
5. The agent sends the token with subsequent gateway requests.

External Identity Flow

When external identity validation is enabled:

1. An agent obtains a JWT from an external identity provider.
2. Synentra validates the token using the configured Authority and JWT settings.
3. The gateway validates issuer and audience depending on:
   • ValidateIssuer
   • ValidateAudience
4. Valid requests continue through the gateway pipeline.

Authentication Headers

By default, Synentra expects tokens in the custom header:

Synentra-Authorization: Bearer <token>

The standard HTTP authorization header can optionally be enabled:

Authorization: Bearer <token>

Example configuration:

"Security": {
  "AgentAuth": {
    "UseCustomHeader": true,
    "CustomHeaderName": "Synentra-Authorization",
    "FallbackToAuthorization": true
  }
}

---

Agent Quarantine

Agent Quarantine automatically blocks an agent’s requests when its TrustScore falls below a configurable threshold.

When quarantine is enabled:

• If an agent’s TrustScore is below TrustScoreFloor, Synentra will persist the agent as Quarantined.
• A quarantined agent receives HTTP 403 Forbidden responses (requests are blocked at the gateway).
• Requests are blocked at the gateway level.
• Quarantine remains active until manually lifted by an operator.

Configuration

Property	Type	Default	Description
Enabled	bool?	true	Enables or disables automatic quarantine checks. If omitted (null), quarantine remains enabled.
TrustScoreFloor	double	0.3	Minimum trust score required before an agent is quarantined.

Example: Default behavior (enabled)

"Security": {
  "AgentAuth": {
    "TokenIssuance": {
      "Secret": "your-signing-secret",
      "Issuer": "synentra",
      "Audience": "synentra-gateway",
      "Expiration": "00:15:00"
    }
  },
  "AgentQuarantine": {
    "Enabled": true,
    "TrustScoreFloor": 0.3
  }
}

Example: Disable quarantine

"Security": { 
  "AgentQuarantine": { 
    "Enabled": false 
  } 
}

---

Secret Management Integration

For production deployments, avoid storing Security.AgentAuth.TokenIssuance.Secret directly in appsettings.json.

Use the Secret Management integration to load signing secrets securely from:

• Environment variables
• Azure Key Vault
• Container secret stores
• Other supported secret providers

For local development, Synentra can automatically generate and persist a signing secret when no secret is configured.