Access Control Lists (ACLs)

This section describes functionality in the JavaScript/TypeScript SDK related to ACLs (Access Control Lists), for information about how the ACLs are defined and control access see Using ACLs.

Default ACL in project templates

If no ACLs are defined at all in a Kalix service, Kalix will allow requests from both other services and the internet to all components of the Kalix service.

The Kalix quickstarts include a less permissive ACL for the entire service, to not accidentally make services available to the public internet, just like the one described in the next section.

Defining an ACL for the entire Kalix Service

A default ACL for the entire Kalix Service can be defined by placing a kalix_policy.proto file among the protobuf descriptors of the service, and including it in your build. It should only contain a (kalix.file).acl annotation:

proto/com/example/kalix_policy.proto
syntax = "proto3";

package com.example;

import "kalix/annotations.proto"; (1)

option (kalix.file).acl = {
  allow: { service: "*" } (2)
};
1 Import the needed Kalix annotations from kalix/annotations.proto
2 Allow access from all other services, but not the public internet

This is the default ACL included in the quickstarts and project templates, it allows calls from any other Kalix service deployed in the same project, but denies access from the internet.

Inspecting the principal inside a service

Checking the ACLs is generally done for you by Kalix, however in some cases programmatic access to the principal of a call can be useful.

Accessing the principal of a call inside of a service is possible through the request metadata Metadata.principals(). The Metadata for a call is available through the context (actionContext, commandContext) of the component.

ACLs when running unit tests

In the unit test Mock components, the ACLs are ignored.

ACLs when running integration tests

When running integration tests, ACLs are disabled by default but can be explicitly enabled per test by running the test with IntegrationTestKitOptions setting aclCheckingEnabled to true.

For integration tests that call other services that have ACLs limiting access to specific service names IntegrationTestKitOptions.withServiceName allows specifying what the service identifies itself as to other services.

IntegrationTestkit.clientsForPrincipal makes it possible to get an integration test client that is authenticated with specific credentials for calling a service with ACLs.