simple-oidc-react-pg

React web app + Keycloak for OpenID Connect + PostgreSQL for all storage.

Infra setup:

• Keycloak runs in local container.
• Keycloak configured to use external PostgreSQL DB instead of the default file-based DB.
• A custom Keycloak realm is imported on first start.
• Keycloak and PG DB data is kept between containers restarts using docker volume.

Keycloak Setup

Accessing Keycloak Admin UI

http://localhost:8080

Admin Credentials:

• Username: admin
• Password: admin

Realm Configuration

The project comes with a pre-configured realm called sample_app_realm that's automatically imported on startup.

What's included:

• ✅ Application realm separate from the master admin realm
• ✅ OIDC client configuration
• ✅ Test users (if configured)
• ✅ Basic security settings

To access your realm:

1. Go to http://localhost:8080
2. Login with admin/admin
3. Switch to sample_app_realm using the dropdown in the top-left corner

Making Changes to Your Realm

If you need to modify the realm configuration:

1. Make changes in Keycloak UI (http://localhost:8080):

   • Switch to sample_app_realm realm (top-left dropdown)
   • Modify clients, users, roles, etc.

2. Export your changes:

   • Go to "Realm settings" → "Action" (dropdown) → "Partial export"
   • Select what to export (clients, users, roles)
   • Click "Export"
   • Save as infra/keycloak-realm.json

3. Test the import:

   • docker-compose -f infra/docker-compose.yml down -v
   • make start
   • Verify your changes are present

⚠️ Important Notes:

• Never export the master realm - it's auto-created and imports will be skipped

• Only include test users with obvious passwords

• Use public clients when possible (no secrets to manage)

• Discovery: http://localhost:8080/realms/sample_app_realm/.well-known/openid-configuration

• Authorization: http://localhost:8080/realms/sample_app_realm/protocol/openid-connect/auth

• Token: http://localhost:8080/realms/sample_app_realm/protocol/openid-connect/token

• UserInfo: http://localhost:8080/realms/sample_app_realm/protocol/openid-connect/userinfo

• Logout: http://localhost:8080/realms/sample_app_realm/protocol/openid-connect/logout

💡 Quick Test: Visit the discovery endpoint to see all available endpoints and configuration.

Connecting to PostgreSQL

http://localhost:8081 - Adminer UI

Connection parameters:

• System: PostgreSQL
• Server: postgres
• Username: pguser
• Password: pgpassword
• Database: sampledb

Keycloak Database:

• Database: keycloak (automatically created)
• Same credentials as above