Skip to main content

Security & Authorization

Orisun authenticates every gRPC call and authorizes a subset of them by role. This page describes both layers and the exact permission each RPC requires.

Authentication​

Every EventStore and Admin call must carry credentials. Two forms are accepted:

  • HTTP Basic, as the authorization metadata header:

    AUTH='Authorization: Basic YWRtaW46Y2hhbmdlaXQ='
    grpcurl -H "$AUTH" localhost:5005 orisun.EventStore/Ping

  • A session token in the x-auth-token header. Every authenticated response sets x-auth-token; a client can send that token on later calls instead of re-sending Basic credentials. The token is validated first, then Basic is used as the fallback.

A missing or malformed header returns UNAUTHENTICATED. Invalid credentials also return UNAUTHENTICATED.

The default account is admin:changeit.

warning

Change ORISUN_ADMIN_PASSWORD before exposing the server, and enable TLS for any non-local deployment. Basic credentials are only as safe as the transport.

Roles​

There are exactly two roles, and they are case-sensitive:

RoleValue
AdministratorADMIN
OperationsOPERATIONS

A role string is stored exactly as supplied and compared exactly. A user created with admin (lowercase) authenticates but matches no role check, so every role-gated call returns PERMISSION_DENIED. Always use the uppercase values.

Permission matrix​

RPCAuthenticationRole required
EventStore/SaveEventsYesADMIN or OPERATIONS
EventStore/CreateIndexYesADMIN
EventStore/DropIndexYesADMIN
EventStore/GetEventsYesAny authenticated user
EventStore/CatchUpSubscribeToEventsYesAny authenticated user
EventStore/PingYesAny authenticated user
Admin/*YesAny authenticated user

Two points worth calling out:

  • Reads and subscriptions are not role-gated. Any authenticated user can read or subscribe to any boundary. Use separate credentials and network controls if you need to restrict who can read event data.
  • Admin RPCs are not role-gated in the handler. Authentication is required, but user management is gated by authentication alone plus per-operation self-rules (a user cannot delete their own account, and ChangePassword only changes the caller's own password). Restrict network access to the Admin surface accordingly.
  • Set a strong ORISUN_ADMIN_PASSWORD and create per-application users with the narrowest role they need: OPERATIONS for services that only save and read events, ADMIN only where index management is required.
  • Enable gRPC TLS and, where mutual auth is needed, ORISUN_GRPC_TLS_CLIENT_AUTH_REQUIRED.
  • Put PostgreSQL, the gRPC port, and NATS cluster routes behind network policy. See the Deployment security checklist.