Configuration

The IAM loads configuration data from a file (typically backed by a Kubernetes config map). The location of the configuration file is sourced from an environment variable. If the service is unable to retrieve the configuration data, it will not start. Refer to the configuration for details.

Service configuration structure

The recommended configuration format is YAML. The below sections describe the officially supported configuration options that influence various aspects of the service functionality. The service may support options other than the ones listed below, but those are not a part of the public API and may be changed or deleted at any time.

General

IAM uses its service instance name and replica ID for communication with other services and load balancing across replicas (for example, see 3/ISM). You can control the values with the following configuration options:

service:
  instance:
    name: <string>          # Service instance name, should be unique cluster-wide. "iam" by default.
    replica.id: <string>    # Service instance replica ID, should be unique cluster-wide. Random string by default.
  graceful-shutdown: <uint> # Allowed service graceful shutdown period in seconds. 30 seconds by default.

The REST API server is controlled with the following options.

server:
  write-timeout: <uint>     # The maximum duration before timing out writes of the response. 5 seconds by default.
  read-timeout: <uint>      # The maximum duration for reading the entire request. 5 seconds by default.
  idle-timeout: <uint>      # IdleTimeout is the maximum amount of time to wait for the next request. 5 seconds by default.
  port: <integer>           # Server port used to expose the REST API at, 8090 by default. Also can be set with the SERVER_PORT environment variable.
  maxPageSize: <string>     # Max pageSize limit, 100 by default.

Policies

You can set up base policies, as well as the resource policy templates via the {service_name} configuration.

Base policies

Base policies serve the purpose of establishing the default set of policies enforced by your {service_name} instance. They are synchronized by {service_name} with the provided configuration on startup. You can’t create base policies via the API, but only from the service configuration.

Base policies support KRNs and KRN wildcards addressing entities across multiple tenants. Is is not possible to create base resource policies, only identity ones.

Make sure you design your base policies especially carefully to avoid inadvertent authorization of undesired operations.

kaa.iam.policies.base:
- krn: <string>             # Policy KRN
  name: <string>            # Policy human-readable name
  type: "identity"          # Policy type; only "identity" is permitted
  description: <string>     # Human-readable policy description
  statements:               # List of policy statements
  - effect: <string>        # Statement effect: "allow" or "deny"
    actions:
    - <string>              # Action identifier
    resources:
    - <string>              # Resource KRN or wildcard KRN
    principals:
    - <string>              # Principal KRN or wildcard KRN
    description: <string>   # Human-readable statement description

The default base policy provisioned by {service_name} allows kaa tenant users any operations in any tenant:

kaa.iam.policies.base:
- krn: "krn:iam:kaa::policy/root-policy"
  name: "root-policy"
  type: "identity"
  statements:
    - effect: "allow"
      actions:
      - "*"
      resources:
      - "krn:iam:kaa:*"
      principals:
      - "krn:iam:kaa::user/*"

Resource policy templates

When a resource server requests creation of a resource in {service_name}, an associated resource policy gets created automatically. Through this configuration, you can control the templates used by {service_name} to create resource policies.

Templates support the following variables that {service_name} substitutes for the actual request values in the process of resource policy creation:

  • ${resourceKRN} expands to the associated resource KRN
  • ${creatorKRN} expands to the KRN of the user who initiated the creation of the associated resource

The configuration structure is as follows:

kaa.iam.policies.resource:
  <resource type name>:     # Name of the associated resource type. "user" and "group" are currently supported.
    krn: <string>           # Policy KRN
    name: <string>          # Policy human-readable name
    type: "resource"        # Policy type; only "resource" is permitted
    description: <string>   # Human-readable policy description
    statements:             # List of policy statements
    - effect: <string>      # Statement effect: "allow" or "deny"
      actions:
      - <string>            # Action identifier
      resources:
      - <string>            # Resource KRN or wildcard KRN
      principals:
      - <string>            # Principal KRN or wildcard KRN
      description: <string> # Human-readable statement description

Default resource policy templates have no statements:

kaa.iam.policies.resource:
  user:
    krn: "${resourceKRN}"
    name: "${resourceKRN}"
    type: "resource"
    description: "Individual resource policy"
    statements:
  group:
    krn: "${resourceKRN}"
    name: "${resourceKRN}"
    type: "resource"
    description: "Individual resource policy"
    statements:

Data persistence interface

IAM uses PostgreSQL for persisting user and group information data.

The following values configure the IAM persistence:

kaa:
  postgres:
    host: <string>                # PostgreSQL host. "127.0.0.1" by default. Also can be set with the KAA_POSTGRESQL_HOST environment variable.
    port: <int>                   # PostgreSQL port. 5432 by default. Also can be set with the KAA_POSTGRESQL_PORT environment variable.
    username: <string>            # PostgreSQL username. "iam" by default. Also can be set with the KAA_POSTGRESQL_USERNAME environment variable.
    password: <string>            # PostgreSQL password. "iam" by default. Also can be set with the KAA_POSTGRESQL_PASSWORD environment variable.
    database: <string>            # PostgreSQL database. "iam" by default. Also can be set with the KAA_POSTGRESQL_DATABASE environment variable.
    sslMode: <string>             # PostgreSQL SSL mode ("disable", "require", "verify-ca", "verify-full"). "disable" by default. Also can be set with the KAA_POSTGRESQL_SSL_MODE environment variable.
    max-open-connections: <int>   # Maximum number of open connections to PostgreSQL. 100 by default. Also can be set with the KAA_POSTGRESQL_MAX_OPEN_CONNECTIONS environment variable.

Authentication, authorization, and multi-tenancy

IAM’s REST API security is implemented according to OAuth2 protocol with a UMA profile. Authentication and authorization is handled within the scope of a given Kaa tenant. Each tenant has a separate OAuth 2.0 issuer, managed by the Kaa Tenant Manager. When multi-tenancy is disabled, all authentication and authorization is conducted in the default system tenant (“kaa”).

IAM security is controlled with the following configuration options (for security reasons it is advised to set these via environment variables).

kaa:
  iam:
    keycloakIDAsUsername: <boolean>   # Replaces username with keycloak user ID when it is enabled. False by default.
  security:
    enabled: <boolean>      # Enables authentication and authorization. False by default.
    issuer:
      public-url: <string>  # OAuth 2.0 issuer public URL for the system tenant ("kaa").
      private-url: <string> # OAuth 2.0 issuer private URL for the system tenant ("kaa").
    client-id: <string>     # Client ID for making requests in the system tenant scope.
    client-secret: <string> # Client secret for making requests in the system tenant scope.
    multitenancy:
      enabled: <boolean>    # Enables multitenancy via integration with the Kaa Tenant Manager. Only effective when kaa.security.enabled is set to true. False by default.
      tenant-manager:
        url: <string>       # URL of the Kaa Tenant Manager that provides security configurations for tenants. "http://tenant-manager" by default.

NATS

The below parameters configure IAM connection to NATS, as well as the NATS message adapters used by IAM. Note that for security reasons NATS username and password are sourced from the environment variables.

nats:
  urls: <comma separated list of URL>  # NATS connection URLs. "nats://nats:4222" by default. Also can be set with the NATS_URLS environment variable.

Logging

IAM writes logs to stdout. By default, the service only produces logs at startup, shutdown, or in case of errors. To enable debug level logging, use the following option:

service:
  debug: <boolean>    # Enables debug level logging, false by default (disabled). Also can be set with the SERVICE_DEBUG environment variable.

Keep in mind that enabling debug level logging will produce significantly more log output and degrade the service performance.

Default configuration

Summarizing the above, the default IAM configuration is as follows.

service:
  instance:
    name: "iam"
    replica.id: "<random string generated on boot>"
  graceful-shutdown: 30
  debug: false
server:
  write-timeout: 5000
  read-timeout: 5000
  idle-timeout: 5000 
  port: 8090
kaa:
  iam:
    keycloakIDAsUsername: false
  postgres:
    host: "127.0.0.1"
    port: "5432"
    username: "iam"
    password: "iam"
    database: "iam"
    sslMode: "disable"
    max-open-connections: 100
  security:
    enabled: false
nats.urls: "nats://nats:4222"