authz-service

Contains full implementation of authz-service domain containing: service implementation, e2e test.

Business description

• Functional Requirements (FR):
  • TODO - team that owns this repository should fill most important information about the project here
• Non Functional Requirements (NFR):
  • stateless
  • multiple instances ready
  • use platform primitives
  • deployable to AWS Kubernetes
  • integrate with other services using API (not db)
  • own your database
  • provide expected testing coverage

Structure

Main maven modules do contain:

• authz-service-service - service implementation, domain model, business logic, infrastructure configuration
• authz-service-contract - contract tests (Judge-d)
• authz-service-e2e - end-to-end tests

Execution

Use docker compose up to locally start required infrastructure (ex. database) based on available docker-compose.yml.

Read service specific README files for more details on how to execute service.

Tests

Test do include include 5 levels/types, described in depth in linked documents:

• service level - validate FR and NFR on localhost
  • unit - business domain flows and small utilities
  • integration - validation of available interfaces and connectivity with external infrastructure using real communication protocol exchange
  • system - black box
• Contract tests - verify API compatibility between services using contract-broker-and-validator Judge-d.
• End 2 End / E2E - black box tests expected to run against external environment (ex. staging).

Contract tests and E2E tests are disabled by default, do read their README for details.

CI/CD

This project includes GitHub Actions workflows that run automatically on pull requests and pushes to main.

Main workflow (.github/workflows/main_pr.yaml)

Pipeline stages:

1. Compile & Package — compiles the project and produces a JAR artifact (shared across subsequent stages)
2. Terragrunt (staging) — runs in parallel with compilation; plans on PRs, applies on main (see Terragrunt workflow below)
3. Checkstyle — runs in parallel with compilation
4. Test fan-out — after compilation, the following test jobs run in parallel:
   • Unit Tests — all tests except integration and system groups
   • Integration Tests — integration-infra-persistence, integration-int-rest-api groups
   • System Tests — system group
5. Docker Build & Test — builds a Docker image, starts it with a PostgreSQL service container, verifies the health endpoint, and pushes to Amazon ECR (on main only)
6. Version tagging — generates a version tag from the PR number/run number and commit hash
7. Deploy to Staging (main only) — after all tests, Docker build, and Terragrunt apply pass, deploys to the staging EKS cluster via the Deploy workflow

Docker Build & Test workflow (.github/workflows/docker-build-test.yaml)

Reusable workflow that:

• Builds a Docker image using remote BuildKitd on EKS
• Optionally builds for multi-arch (linux/amd64 and linux/arm64)
• Starts the image with a PostgreSQL service container and verifies the health endpoint
• Optionally pushes the image to Amazon ECR

Requires AWS OIDC authentication (id-token: write permission).

Deploy workflow (.github/workflows/deploy.yaml)

Reusable workflow that deploys the service to an EKS cluster:

• Assumes an AWS IAM role via OIDC and configures kubectl for the target EKS cluster
• Updates the Kustomize overlay with the new image tag
• Resolves the RDS database name from the service name (strips hyphens and underscores)
• Applies the Kustomize overlay with kubectl apply -k and waits for rollout completion

Requires AWS OIDC authentication (id-token: write permission) and a configured GitHub environment.

Terragrunt workflow (.github/workflows/terragrunt.yaml)

Reusable workflow that manages infrastructure changes via Terragrunt:

• Detects changes in the infra/ directory and skips if none are found
• Runs terragrunt validate and terragrunt plan against the staging environment
• Posts the plan output as a sticky PR comment for review
• In apply mode (main branch only), runs terragrunt apply after a successful plan

Requires AWS OIDC authentication (id-token: write permission) and a GIT_TOKEN secret for accessing private Terraform modules.

Reusable composite actions (.github/actions/)

• maven-setup — sets up JDK 25 and caches Maven dependencies
• maven-run-tests — runs Maven tests with JUnit 5 tag filtering on pre-compiled classes, uploads Surefire reports, and publishes a test report summary

Infrastructure and Kubernetes (/k8s)

Check service readme.

Code Health

This project uses CodeScene for code health analysis. CodeScene monitors code quality on every pull request and flags maintainability issues like complex methods, deep nesting, and code duplication.

How it works

• PR quality gates — CodeScene automatically reviews PRs via GitHub Checks. Configuration is in .codescene/custom-quality-gates.json (Clean Code Collective profile).
• IntelliJ plugin — the project recommends the CodeScene plugin (via .idea/externalDependencies.xml). It shows code health scores and code smells directly in the editor.
• Dashboard — browse hotspots, technical debt trends, and team metrics at codescene.io.

Reading PR results

CodeScene adds a check on your PR with one of these outcomes:

• Pass — no code health issues detected
• Fail (critical) — a critical rule was violated (e.g., Brain Method, Complex Method). Must be fixed before merge.
• Warning (advisory) — a non-blocking suggestion (e.g., Low Cohesion, DRY Violations)

New project onboarding

After generating a project from this template and pushing to GitHub:

1. Log in to CodeScene Cloud
2. Add a new project and link it to the GitHub repository
3. Enable PR integration — the GitHub App is already installed on the catenda organization
4. Select the Clean Code Collective quality profile
5. Run the first analysis and verify it completes successfully

Static Analysis (Qodana)

This project uses Qodana for static code analysis. Qodana runs the same inspections as IntelliJ IDEA in your CI/CD pipeline, catching bugs, security vulnerabilities, and code smells before they reach production.

How it works

• PR quality gates — Qodana scans every PR and compares results against a baseline from main. Any new issue blocks the PR (fail threshold: 0).
• Baseline generation — every push to main runs a full scan and uploads the baseline artifact.
• Workflow — both PR and main scans are handled by .github/workflows/quality-qodana.yaml.
• IntelliJ plugin — the project recommends the Qodana plugin (via .idea/externalDependencies.xml). It lets you run inspections locally and view Qodana Cloud results in the IDE.
• Dashboard — browse detailed results, trends, and issue history at Qodana Cloud.

Configuration

Qodana configuration is in qodana.yaml:

• Linter: jetbrains/qodana-jvm:2025.3 (JDK 25)
• Extra inspections: JvmTaintAnalysis — tracks data flow from untrusted sources (HTTP input) to sensitive operations (SQL, file I/O) to detect injection vulnerabilities
• Excluded: VulnerableLibrariesLocal — dependency vulnerability scanning is disabled until a dedicated tool (Dependabot or Snyk) is set up. Once enabled, you can remove this exclusion from qodana.yaml.

Reading PR results

Qodana adds a check on your PR with:

• Pass — no new issues compared to the baseline
• Fail — one or more new issues detected. Click the check details to see annotated code with descriptions.
• First PR in a new project — if no baseline exists yet (main hasn't been scanned), the PR scan runs without baseline comparison and reports all issues found.

New project onboarding

After generating a project from this template and pushing to GitHub:

1. Log in to Qodana Cloud
2. Create a new project and link it to the GitHub repository
3. Generate a project token
4. Add the token as a GitHub secret named QODANA_TOKEN
5. Push to main to trigger the first baseline scan
6. Verify the scan completes and the baseline artifact is uploaded

Note: Qodana workflows are skipped automatically when QODANA_TOKEN is not configured. Until you complete the onboarding steps above, Qodana will not run.

Further improvements

• Sentry integration
• Add correlation id to logs
• Dependabot — once enabled, remove VulnerableLibrariesLocal from qodana.yaml exclusions (Qodana's dependency scanning becomes redundant)

Infrastructure

• How to create a new RDS database (Staging & Production)

Kubernetes deployment

The service is deployed to EKS using Kustomize with environment-specific overlays:

authz-service-service/src/main/kubernetes/kustomize/
├── base/                    # Shared resources (Deployment, Service, ConfigMap, ServiceAccount, SecretProviderClass)
└── overlays/
    ├── staging/             # Staging-specific config and patches
    └── prod/                # Production-specific config and patches

Key infrastructure components:

• AWS Secrets Manager — database credentials are mounted via the Secrets Store CSI Driver (SecretProviderClass in db-secret.yaml)
• IAM Roles for Service Accounts (IRSA) — the ServiceAccount is annotated with an IAM role ARN for AWS API access (serviceaccount.yaml)
• RDS database name — resolved at deploy time from the service name (hyphens and underscores stripped), injected into config-envs.properties via the Deploy workflow

Terragrunt (IAM roles)

The infra/ directory contains Terragrunt configuration for provisioning AWS infrastructure required by the service. Currently it manages the IRSA IAM role used by the Kubernetes ServiceAccount.

infra/environments/
├── root.hcl                              # Shared config: S3 backend, DynamoDB locking, AWS provider
├── _envcommon/
│   └── iam_roles.hcl                     # Shared IAM role module definition (DRY)
├── staging/
│   ├── profile.hcl                       # AWS profile (dev)
│   └── eu-west-1/
│       ├── env.hcl                       # Backend config + account ID, OIDC provider ID, Secrets Manager ARN
│       ├── region.hcl                    # AWS region
│       └── iam_roles/terragrunt.hcl      # Leaf config — includes root.hcl + _envcommon/iam_roles.hcl
└── prod/
    └── (same structure)

The IAM role module is sourced from catenda/infrastructure (terragrunt/modules/aws_iam_role). The shared definition in _envcommon/iam_roles.hcl reads environment-specific values (aws_account_id, oidc_provider_id, secrets_manager_arn) from each environment's env.hcl. It creates:

• An IAM role with an OIDC trust policy scoped to the service's Kubernetes ServiceAccount
• An inline policy granting secretsmanager:GetSecretValue and secretsmanager:DescribeSecret

Setup after generation: The prod env.hcl contains TODO_REPLACE_* placeholders for the OIDC provider ID and Secrets Manager ARN — these must be filled in before applying. The staging configuration is pre-populated.