Access Control

Qpoint Proxy supports flexible access control mechanisms that can be applied per endpoint to allow or deny access based on IP addresses, user credentials, or JWT claims. SSL/TLS Termination is not required for Access Control.

proxy-config.yaml

proxy: ## Global Settings
  audit_logs: stdout # Where to publish Audit Logs
  jwt_hmac_key: "qwertyuiopasdfghjklzxcvbnm123456"
  default_domain_action: ALLOW

  endpoints: ## Specific Endpoint Settings
  - domain: "api.example.com"
    action: DENY
    allow:
      - ip: 172.17.0.1
      - http-proxy-user: user1:password1
      - http-user: user2:password2
      - id: dog
      - tag: admin

Default Domain Action Configuration

The default_domain_action in Qpoint Proxy's YAML configuration specifies the overarching access rule that applies to all domains not explicitly mentioned in the endpoints section of the configuration file.

• ALLOW: If set to ALLOW, the proxy permits access to all requests by default. This setting is useful in environments where most of the network traffic should be allowed, and only specific domains need to be restricted.

• DENY: Conversely, if set to DENY, the proxy denies access to all requests by default. This is advisable in more secure or sensitive environments where access should be restricted unless explicitly allowed.

Endpoint Allow and Deny Directives

The allow and deny directives define specific exceptions to the action specified at the domain level. Here’s how they work:

• Action: ALLOW – When the action is set to ALLOW, access is permitted by default for all users. The deny directive can be used to specify exceptions where access should be blocked.

  endpoints:
  - domain: "api.example.com"
    action: ALLOW
    deny:

• Action: DENY – When the action is set to DENY, access is blocked by default. The allow directive is used to specify exceptions where access should be permitted.

  endpoints:
  - domain: "api.example.com"
    action: DENY
    allow:

IP-Based Access Control

Access can be controlled based on the IP address of the incoming request. This method is useful for restricting or permitting access from specific network locations.

Both IPV4 and IPV6 are supported. CIDR notation is also supported.

Example Configuration

- domain: "www.example.com"
  action: ALLOW
  deny:
    - ip: 172.17.0.1

In this example, access to www.example.com is generally allowed, but requests from the IP address 172.17.0.1 are denied.

- domain: "www.yahoo.com"
  action: DENY
  allow:
    - ip: "172.17.0.0/16"

Conversely, for www.yahoo.com, access is denied by default except for requests coming from 172.17.0.0/16.

Username/Password Based Access Control

Access can also be controlled using traditional username and password credentials, either via HTTP basic authorization or proxy authorization.

Example Configuration

- domain: "api.github.com"
  action: DENY
  allow:
    - http-proxy-user: user1:password1
    - http-user: user2:password2

In this configuration, access is generally denied, except for specified users who authenticate successfully.

JWT-Based Access Control

JWT is a compact, URL-safe means of representing claims to be transferred between two parties. In the context of Qpoint Proxy, JWTs are used to securely transmit information about a user between the client and the server, enabling the server to enforce access controls based on the contents of the token.

Configuring JWT Claims in YAML

First, the proxy administrator sets up the proxy to check certain JWT claims against its access rules. This is done within the endpoints configuration in the proxy-config.yaml file.

Example Configuration

proxy:
  audit_logs: stdout
  jwt_hmac_key: "qwertyuiopasdfghjklzxcvbnm123456"
  ...
  endpoints:
    - domain: "api.github.com"
      action: DENY
      allow:
        - id: "dog"
        - tag: "admin"

Matching JWT Claims with YAML Configuration

When a JWT is presented to the proxy (typically included in the Authorization header of the request as a Bearer token), Qpoint Proxy performs several steps to determine if the request should be allowed or denied:

1. Extraction and Verification:

   • The JWT is extracted from the Authorization header.

   • The proxy validates the JWT using the configured jwt_hmac_key to ensure it is authentic and has not been tampered with.

2. Claim Evaluation Against Configuration:

   • Subject (sub) Claim: The proxy checks if the sub claim in the JWT matches any id specified in the allow list for the domain. In the above example, if the JWT's sub is "dog", and the configuration specifies an id of "dog", the request would be considered for allowance.

   • Tags Claim: Similarly, the proxy checks if any of the tags in the JWT match the tags specified in the allow list. If the JWT includes the tag "admin" and the YAML configuration under that domain includes tag: "admin", the request will be allowed.

3. Final Decision:

   • If any of the JWT claims match the allowed conditions in the configuration, the request is permitted.

   • If no claims match, or if the specified action is DENY without a corresponding allow condition being met, the request is denied.

Practical Example

Consider a JWT with the following payload:

{
    "iss": "Qpoint.io",
    "iat": 1715358511,
    "exp": 1715358512,
    "aud": "www.example.com",
    "sub": "dog",
    "tags": [
        "admin",
        "user"
    ]
}

For a request to api.github.com, Qpoint Proxy checks:

• If the sub matches "dog", the condition is satisfied.

• If one of the tags matches "admin", the condition is also satisfied.

Since either or both conditions meet the allow criteria in the YAML configuration, the request would be allowed even though the default action is DENY.

Testing Access Control with Qpoint Proxy

To verify that Qpoint Proxy is correctly handling access control based on your configuration, you can use curl commands to simulate requests with different types of authentication. Below are examples for each method:

Connect with Proxy Authorization

When testing proxy authorization, use the --proxy-user option in curl to pass the credentials.

curl -k -I -X GET --proxy-user user1:password1 https://api.github.com --proxy http://127.0.0.1:10443

This command configures curl to use user1 with password1 as credentials for proxy authorization to access api.github.com through your proxy.

Connect with Proxy Authorization using JWT

When you need to authenticate with the proxy using a JWT, you can include the JWT in the --proxy-user option. Here's an example:

curl -k -I -X GET --proxy-user Devin:$JWT https://api.github.com --proxy http://127.0.0.1:10443

This command configures curl to use Devin with the provided JWT as credentials for proxy authorization to access api.github.com through your proxy.

Basic Authentication with Username/Password

For a more traditional approach using Basic Authentication with a username and password, you can simulate this as follows:

curl -k -I -X GET -H "X-Qpoint-Authorization: Basic dXNlcjI6cGFzc3dvcmQy" https://api.github.com:10443/ --resolve 'api.github.com:10443:127.0.0.1'

This command sends a GET request to api.github.com with a Basic Auth header, where dXNlcjI6cGFzc3dvcmQy is the Base64-encoded string of user2:password2.

Basic Authentication with JWT as Password

You can use Basic Authentication where the JWT is used as the password part of the credential.

curl -k -I -X GET -H "X-Qpoint-Authorization: Bearer ZG9nOmV5SjBlWEFpT2lKS1YxUWlMQ0poYkdjaU9pSklVekkxTmlKOS5leUpwYzNNaU9pSlBibXhwYm1VZ1NsZFVJRUoxYVd4a1pYSWlMQ0pwWVhRaU9qRTNNVFV4TnpZNU1EQXNJbVY0Y0NJNk1UYzBOamN4TWprd01Dd2lZWFZrSWpvaVlYQnBMbWRwZEdoMVlpNWpiMjBpTENKemRXSWlPaUprYjJjaUxDSjBZV2R6SWpwYkltRnNiR1J2WjNNaUxDSmhaRzFwYmlKZGZRLlMyWGFzY3gzTDhCQnlaV0dqRXdLVTNmQU41TGEyMjIyVEJGYkQ4UWhHSUU=" https://api.github.com:10443/ --resolve 'api.github.com:10443:127.0.0.1'

This command sends a GET request to api.github.com using a Basic Auth header.

Verifying the Responses

When you run these commands, look for HTTP status codes in the responses:

• 2XX indicates successful access.

• 403 indicates forbidden access.