platform-orchestrator-iam

README

Platform Orchestrator IAM

Platform Orchestrator IAM is the identity and access management service for the Stellwerk Platform Orchestrator. It provides APIs for:

1. User login and user management
2. User membership and role-based access control through SpiceDB
3. API tokens for service users and accounts

Organizations are owned by platform-orchestrator-cp; users can be members of one, many, or no organizations.

Requirements

• Go version declared in go.mod
• yq v4
• Docker with BuildKit and Docker Compose for integration tests
• score-compose 0.17 or newer for integration tests

All Go modules and container images used by this repository are intended to be public. Local builds and tests do not require GitHub package or private-module credentials.

Generate and test

Generate API clients, events, and mocks before running tests:

make generate
make test-unit
go vet ./...

Run the integration suite and clean up its containers with:

make test-integration
make clean

The integration environment is generated by score-compose from score.yaml and integration-tests/score.cp.yaml. It includes:

• platform-orchestrator-iam, built from this source
• platform-orchestrator-iam-self-hosted, a second IAM instance configured with Keycloak to exercise self-hosted authentication flows
• platform-orchestrator-cp, pulled from ghcr.io/stellwerk-labs/platform-orchestrator-cp:v1.0.1
• PostgreSQL, RabbitMQ, SpiceDB, Vault, Keycloak, and nginx

Database

The service uses PostgreSQL through raw SQL queries. Database migrations use Goose and are embedded from internal/model/migrations/.

• Add migrations as internal/model/migrations/00000N_description.sql.
• The database interface is defined in internal/model/databaser.go.
• Optional transactions use the Tx interface.

API changes

When adding an endpoint, update the routing configuration in the Score files as well as the OpenAPI specification. Missing routing patterns can cause nginx to return 405 Method Not Allowed even when the service implements the endpoint.

Run make generate after changing openapi/spec.yaml or openapi/events.yaml, and commit the regenerated API and event sources.

Compatibility

This repository's distribution ownership is moving to stellwerk-labs, but platform-orchestrator-* service names, API paths, configuration environment variables, Score workload/resource identifiers, event contracts, and database contracts remain unchanged. They are product and integration interfaces rather than legacy GitHub ownership, and renaming them would break existing clients and deployments.

The OSS migration does not change OIDC, OAuth, SSO, session, token, or other authentication protocol behavior, endpoints, identifiers, environment variables, or test fixtures.

Releases

The CI workflow validates generated sources, modules, unit tests, vet, lint, and integration tests. Releases from main use stellwerk-labs/semantic-release-action and publish the service image as ghcr.io/stellwerk-labs/platform-orchestrator-iam:<version> for AMD64 and ARM64.

The nested public Go module in shared/ is versioned with shared/v* tags.

License

Licensed under the European Union Public Licence 1.2.