Gatekeeper Security Proxy

You can increase security by using HMAC signatures for request verification or signing.

• Signing: Enabled via --enable-hmac in forward-signing mode. Gatekeeper creates a signature and passes it in the X-HMAC-SHA256 header.
• Verification: Performed when using Gatekeeper as an authentication/authorization proxy.

The signature is generated by signing a string formatted as follows:

stringToSign := fmt.Sprintf(
	"%s\n%s%s\n%s;%s;%s",
	req.Method,
	req.URL.Path,
	req.URL.RawQuery,
	req.Header.Get(constant.AuthorizationHeader),
	req.Host,
	sha256.Sum256(body),
)

Gatekeeper provides two levels of default deny behavior:

1. --enable-default-deny-strict (Recommended/Default in 5.0.0): Blocks all requests (even with valid tokens) unless a specific path and requirement are explicitly defined in the resources configuration. This is the safest setting for production.
2. --enable-default-deny: Blocks all requests that lack a valid token for basic HTTP methods (DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE). Note that this does not check for specific claims or roles within the token.

When protecting servers that use Server-Side Events (SSE), be aware that Gatekeeper's timeout settings correspond to Go's http.Server implementation:

• --server-write-timeout: The maximum duration before timing out writes of the response. Since SSE involves long-lived connections without new request headers being sent, this timeout will trigger and disconnect the client.
• --server-idle-timeout: The maximum amount of time to wait for the next request when keep-alives are enabled.

To prevent SSE clients from being disconnected, disable the write timeout by setting: --server-write-timeout=-1s.

Gatekeeper allows you to restrict access to specific URIs and HTTP methods based on roles found in the token claims.

By default, all roles listed under a resource perform a logical AND (all must be present). You can change this to a logical OR (at least one must be present) using the require-any-role option.

Roles can be matched against:

• Realm roles: Use the role name directly (e.g., examplerealmrole).
• Client roles: Use the format client_id:role_name (e.g., client1:test1).

If roles are stored in custom claims, refer to the claim matching documentation.

resources:
- uri: /admin*
  methods:
  - GET
  roles:
  # Matches realm role
  - examplerealmrole
  # Matches client roles (client1's test1 and client2's test2)
  - client1:test1
  - client2:test2

Level of Authentication (LoA) or ACR (Authentication Context Class Reference) allows you to require a higher level of authentication for specific resources.

To use this, enable --enable-loa=true and specify the required acr levels in your resource configuration.

Example:

• /cats accepts level1 or level2. If the user only has level1, they are redirected to authenticate for level1 (default).
• /pets requires level2. If the user only has level1, they are redirected to authenticate for level2.

--resources=uri=/cats|acr=level1,level2
--resources=uri=/pets|acr=level2

Gatekeeper supports different flows depending on your application type:

• Frontend Server-side Apps: Use the Authorization Code Flow (with PKCE) which involves redirects.
• APIs: Use the Client Credentials Grant. To avoid redirection steps in API mode, set --no-redirects=true.

Mixed Mode Configuration: You can configure both flows on the same Gatekeeper instance by setting a global no-redirects: false and overriding specific resources with no-redirect: true.

Note: You cannot override a global no-redirects: true setting to false within a resource; you can only override false to true.

# Global setting: Authorization Code Flow enabled
no-redirects: false
resources:
- uri: /api/v1/*
  methods:
    - GET
  no-redirect: true # API mode enabled for this resource
- uri: /api/v2/*
  methods:
    - GET
  no-redirect: true

Gatekeeper can proxy Websocket servers using standard upgrade headers. Because browsers do not enforce CORS for the Websocket protocol, you should implement additional security measures to ensure connections only originate from authorized sources.

Recommended Security Measures:

1. Enable encrypted tokens using --enable-encrypted-token and provide an --encryption-key.
2. Verify the Origin header using Headers matching.

If these measures are not taken, Gatekeeper treats Websocket connections as standard proxy traffic without special setup.

When designing authorization rules, follow a 'deny-by-default' security model:

1. Be Explicit: Avoid broad wildcards in 'allow' rules. Instead of matching /app/* with a general user role, define specific paths like /app/admin with an ADMIN_ROLE.
2. Use the deny attribute: In version 5.0.0+, use deny: true on specific URIs to explicitly block access rather than relying on unused roles.
3. Order of Specificity: Define more specific rules before broader catch-all rules to prevent accidental access to sensitive sub-paths.

resources:
  - uri: /*
    deny: true
  - uri: /app/admin
    roles:
      - ONLY_ADMIN
  - uri: /app/users
    roles:
      - ONLY_USER_MANAGER_ROLE