Getting Started

Keycloak is an open source identity and access management solution. It provides single sign-on (SSO), OAuth2/OIDC authorization, SAML 2.0, user federation, social login, and a central admin console — all without writing authentication code. This guide walks you through deploying Keycloak on Eyevinn Open Source Cloud.

Prerequisites

Step 1: Create a PostgreSQL database

Keycloak requires a PostgreSQL database. Navigate to the PostgreSQL service and click Create psql-db. Enter a name and a password.

The connection URL is:

postgres://postgres:<password>@<IP>:<PORT>/postgres

Step 2: Store credentials as secrets

Navigate to the Keycloak service page, open the Service Secrets tab, and create:

  • dburl — the PostgreSQL connection URL from Step 1
  • adminpassword — your chosen admin password (use a strong password)

Step 3: Create the Keycloak instance

Click Create keycloak and fill in:

Field Value
Name Unique identifier (alphanumeric, e.g. mykeycloak)
DatabaseUrl {{secrets.dburl}}
AdminUser Admin username (e.g. admin)
AdminPassword {{secrets.adminpassword}}

Wait until the instance status is green and shows running.

Step 4: Log in to the admin console

Open the instance URL in your browser and navigate to /admin. Log in with the AdminUser and AdminPassword you set in Step 3.

From the admin console you can:

  • Create realms to isolate application environments
  • Register clients (applications) that will delegate authentication to Keycloak
  • Manage users, roles, and groups
  • Configure identity providers (Google, GitHub, SAML, LDAP, etc.)

Step 5: Register a client application

  1. In the admin console, select your realm (or create a new one)
  2. Go to Clients and click Create client
  3. Choose OpenID Connect as the protocol
  4. Set the Client ID to your application name
  5. Add your application's callback URL as a valid redirect URI
  6. Save and copy the client secret from the Credentials tab

Your application can now authenticate users via the standard OIDC endpoints:

Authorization: https://<instance-url>/realms/<realm>/protocol/openid-connect/auth
Token:         https://<instance-url>/realms/<realm>/protocol/openid-connect/token
Userinfo:      https://<instance-url>/realms/<realm>/protocol/openid-connect/userinfo

Usage example (Node.js)

import Keycloak from 'keycloak-connect';
import session from 'express-session';
import express from 'express';

const app = express();
const memoryStore = new session.MemoryStore();
app.use(session({ secret: 'some secret', store: memoryStore }));

const keycloak = new Keycloak({ store: memoryStore }, {
  realm: 'myrealm',
  'auth-server-url': 'https://<instance-url>',
  'ssl-required': 'external',
  resource: 'my-client',
  'confidential-port': 0,
});

app.use(keycloak.middleware());

app.get('/protected', keycloak.protect(), (req, res) => {
  res.json({ message: 'Authenticated!' });
});

app.listen(3000);

CLI usage

# First create a PostgreSQL database
osc create birme-osc-postgresql mydb -o PostgresPassword="mypassword"

# Create the Keycloak instance
osc create keycloak-keycloak mykeycloak \
  -o DatabaseUrl="postgres://postgres:mypassword@<IP>:<PORT>/postgres" \
  -o AdminUser="admin" \
  -o AdminPassword="<strong-password>"

Resources