Securing the API involves configuring OPA to use TLS, authentication, and authorization so that:

  • Traffic between OPA and clients is encrypted.
  • Clients verify the OPA API endpoint identity.
  • OPA verifies client identities.
  • Clients are only granted access to specific APIs or sections of The data Document.

HTTPS is configured by specifying TLS credentials via command line flags at startup:

  • specifies the path of the file containing the TLS certificate.
  • --tls-private-key-file=<path> specifies the path of the file containing the TLS private key.

OPA will exit immediately with a non-zero status code if only one of these flags is specified.

Note that for using TLS-based authentication, a CA cert file can be provided:

  • --tls-ca-cert-file=<path> specifies the path of the file containing the CA cert.

If provided, it will be used to validate clients’ TLS certificates when using TLS authentication (see below).

By default, OPA ignores insecure HTTP connections when TLS is enabled. To allow insecure HTTP connections in addition to HTTPS connections, provide another listening address with --addr. For example:

  1. openssl genrsa -out private.key 2048
  2. openssl req -new -x509 -sha256 -key private.key -out public.crt -days 1

2. Start OPA with TLS enabled

  1. opa run --server --log-level debug \
  2.     --tls-cert-file public.crt \
  3.     --tls-private-key-file private.key
  1. curl http://localhost:8181/v1/data

4. Access the API with HTTPS

  1. curl -k https://localhost:8181/v1/data

This section shows how to configure OPA to authenticate and authorize client requests. Client-side authentication of the OPA API endpoint should be handled with TLS.

Authentication and authorization allow OPA to:

  • Verify client identities.
  • Control client access to APIs and data.

Both are configured via command line flags:

  • --authentication=<scheme> specifies the authentication scheme to use.
  • --authorization=<scheme> specifies the authorization scheme to use.

By default, OPA does not perform authentication or authorization and these flags default to off.

For authentication, OPA supports:

  • : Bearer tokens are enabled by starting OPA with --authentication=token. When the token authentication mode is enabled, OPA will extract the Bearer token from incoming API requests and provide to the authorization handler. When you use the token authentication, you must configure an authorization policy that checks the tokens. If the client does not supply a Bearer token, the input.identity value will be undefined when the authorization policy is evaluated.

  • Client TLS certificates: Client TLS authentication is enabled by starting OPA with --authentication=tls. When this authentication mode is enabled, OPA will require all clients to provide a client certificate. It is verified against the CA certificate(s) provided via --tls-ca-cert-path. Upon successful verification, the input.identity value is set to the TLS certificate’s subject.

For authorization, OPA relies on policy written in Rego. Authorization is enabled by starting OPA with --authorization=basic.

When the basic authorization scheme is enabled, a minimal authorization policy must be provided on startup. The authorization policy must be structured as follows:

  1. # The "system" namespace is reserved for internal use
  2. # by OPA. Authorization policy must be defined under
  3. # system.authz as follows:
  4. package system.authz
  6. default allow = false  # Reject requests by default.
  8. allow {
  9.   # Logic to authorize request goes here.
  10. }

When OPA receives a request, it executes a query against the document defined data.system.authz.allow. The implementation of the policy may span multiple packages however it is recommended that administrators keep the policy under the system namespace.

If the document produced by the allow rule is true, the request is processed normally. If the document is undefined or not true, the request is rejected immediately.

OPA provides the following input document when executing the authorization policy:

  1. {
  2.     # Identity established by authentication scheme.
  3.     # When Bearer tokens are used, the identity is
  4.     # set to the Bearer token value.
  5.     "identity": "",
  7.     # One of {"GET", "POST", "PUT", "PATCH", "DELETE"}.
  8.     "method": "",
  10.     # URL path represented as an array.
  11.     # For example: /v1/data/exempli-gratia
  12.     # is represented as ["v1", "data", "exampli-gratia"]
  13.     "path": [...],
  15.     # URL parameters represented as an object of string arrays.
  16.     # For example: metrics&explain=true is represented as
  17.     # {"metrics": [""], "explain": ["true"]}
  18.     "params": {"...": ...},
  20.     # Request headers represented as an object of string arrays.
  21.     #
  22.     # Example Request Headers:
  23.     #
  24.     #   host: acmecorp.com
  25.     #   x-custom: secretvalue
  26.     #
  27.     # Example input.headers Value:
  28.     #
  29.     #   {"Host": ["acmecorp.com"], "X-Custom": ["mysecret"]}
  30.     #
  31.     # Example header check:
  32.     #
  33.     #   input.headers["X-Custom"][_] = "mysecret"
  34.     #
  35.     # Header keys follow canonical MIME form. The first character and any
  36.     # characters following a hyphen are uppercase. The rest are lowercase.
  37.     # If the header key contains space or invalid header field bytes,
  38.     # no conversion is performed.
  39.     "headers": {"...": [...]},
  41.     # Request message body if present for applicable APIs.
  42.     #
  43.     # Example Request:
  44.     #
  45.     #   POST v1/data HTTP/1.1
  46.     #   Content-Type: application/json
  47.     #
  48.     #   {"input": {"action": "trade", "stock": "ACME"}}
  49.     #
  50.     # Example input.body Value:
  51.     #   {"input": {"action": "trade", "stock": "ACME"}}
  52.     #
  54.     #
  55.     #   input.body.input.stock == "ACME"
  56.     #
  57.     # The 'body' field is provided for the following APIs:
  58.     #
  59.     #   * POST v1/data
  60.     #   * POST v0/data
  61.     #   * POST /
  62.     "body": ...,
  63. }

At a minimum, the authorization policy should grant access to a special root identity:

  1. package system.authz
  3. default allow = false           # Reject requests by default.
  5. allow {                         # Allow request if...
  6.     "secret" == input.identity  # Identity is the secret root key.
  7. }

When OPA is configured with this minimal authorization policy, requests without authentication are rejected:

Response:

  1. HTTP/1.1 401 Unauthorized
  2. Content-Type: application/json
  1. {
  2.   "code": "unauthorized",
  3.   "message": "request rejected by administrative policy"
  4. }

However, if Bearer token authentication is enabled and the request includes the secret from above, the request is allowed:

  1. GET /v1/policies HTTP/1.1
  2. Authorization: Bearer secret

Response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json

Besides boolean responses, authorization policies can change the message included in the deny response. Do do that, policy decisions must yield an object response as follows:

  1. package system.authz
  3. default allow = {
  4.     "allowed": false,
  5.     "reason": "unauthorized resource access"
  6. }
  8. allow = { "allowed": true } {   # Allow request if...
  9.     "secret" == input.identity  # identity is the secret root key.
  10. }
  12. allow = { "allowed": false, "reason": reason } {
  13.     not input.identity
  14.     reason := "no identity provided"
  15. }

When Bearer tokens are used for authentication, the policy should at minimum validate the identity:

  1. package system.authz
  3. # Tokens may defined in policy or pushed into OPA as data.
  4. tokens = {
  5.     "my-secret-token-foo": {
  6.         "roles": ["admin"]
  7.     },
  8.     "my-secret-token-bar": {
  9.         "roles": ["service-1"]
  10.     },
  11.     "my-secret-token-baz": {
  12.         "roles": ["service-2", "service-3"]
  13.     }
  14. }
  16. default allow = false           # Reject requests by default.
  18. allow {                         # Allow request if...
  19.     input.identity == "secret"  # Identity is the secret root key.
  20. }
  22. allow {                        # Allow request if...
  23.     tokens[input.identity]     # Identity exists in "tokens".
  24. }

To complete this example, the policy could further restrict tokens to specific documents:

  1. package system.authz
  3. # Rights may be defined in policy or pushed into OPA as data.
  4. rights = {
  5.     "admin": {
  6.         "path": "*"
  7.     },
  8.     "service-1": {
  9.         "path": ["v1", "data", "exempli", "gratia"]
  10.     },
  11.     "service-2": {
  12.         "path": ["v1", "data", "par", "example"]
  13.     }
  14. }
  16. # Tokens may be defined in policy or pushed into OPA as data.
  17. tokens = {
  18.     "my-secret-token-foo": {
  19.         "roles": ["admin"]
  20.     },
  21.         "roles": ["service-1"]
  22.     },
  23.     "my-secret-token-baz": {
  24.         "roles": ["service-2", "service-3"]
  25.     }
  26. }
  28. default allow = false               # Reject requests by default.
  30. allow {                             # Allow request if...
  31.     some right
  32.     identity_rights[right]          # Rights for identity exist, and...
  33.     right.path == "*"               # Right.path is '*'.
  34. }
  36. allow {                             # Allow request if...
  37.     some right
  38.     identity_rights[right]          # Rights for identity exist, and...
  39.     right.path == input.path        # Right.path matches input.path.
  40. }
  42. identity_rights[right] {             # Right is in the identity_rights set if...
  43.     some role
  44.     token := tokens[input.identity]  # Token exists for identity, and...
  45.     role := token.roles[_]           # Token has a role, and...
  46.     right := rights[role]            # Role has rights defined.
  47. }

TLS-based Authentication Example

To set up authentication based on TLS, we will need three certificates:

  1. the CA cert (self-signed),
  2. the server cert (signed by the CA), and
  3. the client cert (signed by the CA).

These are example invocations using openssl. Don’t use these in production, the key sizes are only good for demonstration purposes.

We also create a simple authorization policy file, called check.rego:

  1. package system.authz
  3. # client_cns may defined in policy or pushed into OPA as data.
  4. client_cns = {
  5.     "my-client": true
  6. }
  8. default allow = false
  10. allow {                                        # Allow request if
  11.     split(input.identity, "=", ["CN", cn]) # the cert subject is a CN, and
  12.     client_cns[cn]                         # the name is a known client.
  13. }

Now, we’re ready to starting the server with -authentication=tls and the certificate-related parameters:

  1. $ opa run -s \
  2.   --tls-cert-file server-cert.pem \
  3.   --tls-private-key-file server-key.pem \
  4.   --tls-ca-cert-file ca.pem \
  5.   --authentication=tls \
  6.   --authorization=basic \
  7.   -a https://127.0.0.1:8181 \
  8.   check.rego
  9. INFO[2019-01-14T10:24:52+01:00] First line of log stream.                     addrs="[https://127.0.0.1:8181]" insecure_addr=

We can use curl to validate our TLS-based authentication setup:

First, we use the client certificate that was signed by the CA, and has a subject matching our authorization policy:

  1. $ curl --key client-key.pem \
  2.   --cert client-cert.pem \
  3.   --cacert ca.pem \
  4.   --resolve opa.example.com:8181:127.0.0.1 \
  5.   https://opa.example.com:8181/v1/data
  6. {"result":{}}

Note that we’re passing the CA cert to curl – this is done to have curl accept the server’s certificate, which has been signed by our CA cert.

Since we’ve setup an IP SAN, we may also curl https://127.0.0.1:8181/v1/data directly. (To keep our examples focused, we’ll do that from here on.)

Using a valid certificate whose subject will be declined by our authorization policy:

  1. $ curl --key client-key-2.pem \
  2.   --cert client-cert-2.pem \
  3.   --cacert ca.pem \
  4.   https://127.0.0.1:8181/v1/data
  5. {
  6.   "code": "unauthorized",
  7.   "message": "request rejected by administrative policy"
  8. }

Finally, we’ll attempt to query without a client certificate:

  1. $ curl --cacert ca.pem https://127.0.0.1:8181/v1/data
  2. curl: (35) error:14094412:SSL routines:ssl3_read_bytes:sslv3 alert bad certificate

As you can see, TLS-based authentication disallows these request completely.

Often OPA is deployed locally to the host where the client resides (side-car or similar model). In these deployments it is ideal to only expose the API via localhost to prevent any remote clients from reaching OPA at all. The downside to this approach is that it blocks remote monitoring systems that require access to /health or /metrics.

The solution is to configure OPA with a separate diagnostic listener by providing the --diagnostic-addr flag, for example:

  1. $ opa run \
  2.   -s \
  3.   --addr localhost:8181 \
  4.   --diagnostic-addr :8282

The configuration above would expose only /health and /metrics API’s on port 8282 while keeping the normal REST API bound to localhost:8181.

You can run a hardened OPA deployment with minimal configuration. There are a few things to keep in mind:

  • Limit API access to host-local clients executing policy queries.
  • Configure TLS (for localhost TCP) or a UNIX domain socket.
  • Do not pass credentials as command-line arguments.
  • Run OPA as a non-root user ideally inside it’s own account.

With OPA configured to fetch policies using the feature you can configure OPA with a restrictive authorization policy that only grants clients access to the default policy decision, i.e., POST /:

  1. package system.authz
  3. # Deny access by default.
  4. default allow = false
  6. # Allow anonymous access to the default policy decision.
  7. allow {
  8.     input.method = "POST"
  9.     input.path = [""]
  10. }
  • Authorize all API requests (--authorization=basic)
  • Listen on localhost for HTTPS (not HTTP!) connections (--addr, --tls-cert-file, --tls-private-key-file)
  • Download bundles from a remote HTTPS endpoint (--set flags and flag)