Authentication for Local Development

This guide covers how authentication works in the local development environment, including Keycloak setup and login procedures.

Keycloak Setup

Keycloak runs at http://localhost:8081 and is automatically configured with realm imports when you run make start-deps.

Keycloak Admin Console

• URL: http://localhost:8081
• Username: admin
• Password: admin

Realms

Realm	Purpose	Used by
internal	Administrative users	Admin Panel
customer	Bank customers	External customer clients, customer-server API

Realm definitions are stored in dev/keycloak/ and imported automatically on startup.

Admin Panel Login

1. Navigate to http://admin.localhost:4455
2. You'll be redirected to Keycloak
3. Log in with: admin@galoy.io
4. The admin panel uses the internal Keycloak realm with OIDC Code Flow

Customer API Login

The bank no longer ships an in-repo customer-facing web frontend. The customer-server (port 5254) is exposed at http://app.localhost:4455/graphql for:

• External customer clients that drive their own OIDC login against the Keycloak customer realm. The reference client is lana-mobile-demo — if you change the customer realm, the customer-server schema, or the app.localhost Oathkeeper route, check that demo still works.
• Bats tests, which use the dev direct-grant (password) flow to obtain a Keycloak access token — see get_customer_access_token in bats/helpers.bash.

Authentication Flow

How Oathkeeper Works

Oathkeeper sits at port 4455 and handles all authentication:

1. Receives incoming requests with Bearer JWT tokens
2. Validates the JWT signature against Keycloak's JWKS endpoint
3. Issues an internal JWT with route-specific audience and user subject
4. Proxies the request to the appropriate upstream service (admin-server or customer-server)

The backend servers only accept internal JWTs from Oathkeeper — they verify using Oathkeeper's JWKS and check the audience claim.

Token Lifetimes (Development)

Token	Lifetime
Access token	5 minutes
Refresh token	30 minutes
Session	8 hours