Skip to content

Auth and RBAC with Keycloak

You can try the role-based access control of Quine Enterprise and Novelty on your own machine, signing in as a sample user for each role, without setting up an identity provider. With services.auth: keycloak, quinectl starts a local Keycloak, creates a realm for each product with the product's roles and a set of sample users, and configures the product to require auth. The web UI then asks you to sign in, and the REST API needs a bearer token.

Auth needs edition: enterprise in the quine: block, and works for Novelty too. The default Quine Enterprise file from quinectl init already has auth: keycloak:

quinectl.yaml
quine:
  edition: enterprise
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
services:
  persistor: cassandra
  auth: keycloak
  proxy: none
  metrics: none
  kafka: none

Keycloak listens on https://localhost:8443. Every project on the machine shares the one Keycloak. Projects that keep the default realm name share that realm and its users, so give each project its own realm; see Multi-tenancy.

Roles and sample users

Each product's realm has six roles, SuperAdmin, SRE, Architect, DataEngineer, Analyst and Billing, and one sample user per role. The end of the quinectl status output lists them:

sample users:
  username       password         roles
  superadmin1    superadmin123    SuperAdmin
  sre1           sre123           SRE
  architect1     architect123     Architect
  dataengineer1  dataengineer123  DataEngineer
  analyst1       analyst123       Analyst
  billing1       billing123       Billing

caveat: dev credentials — local development only

What each role may do is described in OIDC Authentication and RBAC.

Anyone who can reach the port can sign in as a sample user

The sample users' passwords are published on this page and fixed in quinectl, so use them for local development only. Change the users before you expose the port beyond your machine; see Your own users.

Your own users

To choose your own users instead, list them. quinectl creates them and keeps their passwords and roles as written on every up. A listed user that already exists in the realm is taken over. A user quinectl created or took over is deleted once you no longer list it:

quinectl.yaml
quine:
  edition: enterprise
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
  users:
    - {username: alice, password: alice-pass, roles: [Architect]}
    - {username: bob, password: "${BOB_PASSWORD}", roles: [Analyst, Billing]}
services:
  persistor: cassandra
  auth: keycloak
  proxy: none
  metrics: none
  kafka: none

Keep passwords out of the file

Write a password as ${VARIABLE} and quinectl reads it from the environment on every up. For example, a single SuperAdmin:

quinectl.yaml
quine:
  edition: enterprise
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
  users:
    - {username: admin, password: "${QUINE_ADMIN_PASSWORD}", roles: [SuperAdmin]}
services:
  persistor: cassandra
  auth: keycloak
  proxy: none
  metrics: none
  kafka: none
export QUINE_ADMIN_PASSWORD=<a password>
quinectl up
quinectl token --user admin

quinectl doesn't write the password to any file. The end of the quinectl status output names the variable in its place:

sample users:
  username  password                      roles
  admin     (from $QUINE_ADMIN_PASSWORD)  SuperAdmin

caveat: dev credentials — local development only

Change the variable and run up again to change the password. If the variable is unset or empty, up stops with an error naming it before it launches Quine Enterprise.

users: [] creates none, and seedTestUsers: false leaves the realm's users alone entirely. The realm, client id, roles and session length can all be changed. If a roles list of your own leaves out SRE, quinectl adds it, because up needs that role; see the quinectl.yaml Reference.

Bearer tokens for the REST API

quinectl token signs in as a sample user and prints the access token, ready for an Authorization header:

curl -s -X POST http://localhost:8080/api/v2/graph/quine/cypher:query \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $(quinectl token)" \
  -d '{"text":"RETURN 1"}'
  • By default it signs in as the first user, superadmin1. --user analyst1 picks another. A name that isn't one of the configured users is refused with the list of valid ones.
  • With both products running, --product novelty signs in to Novelty's realm.
  • Tokens expire after five minutes (expiresIn: 300 in quinectl token --json). Call quinectl token inside each command, as above, rather than saving the token.
  • It needs a previous quinectl up, and never prints a user's password or the client secret.

Trusting the local certificate

The first quinectl up with Keycloak creates a local certificate authority at ~/.quinectl/state/certs/ca.pem and uses it for Keycloak's HTTPS certificate. Your browser doesn't know it, so the sign-in page shows a certificate warning until you trust it.

On macOS, add it to your login keychain once per machine. Safari and Chrome then accept it:

quinectl trust

To check whether it is trusted, or to take it out again:

quinectl trust --status     # check, without changing anything
quinectl trust --remove     # take it out again

Firefox has its own certificate list. Import ~/.quinectl/state/certs/ca.pem under Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import.

On Linux and Windows, import the same file into your browser or system certificate store, or accept the warning on the sign-in page.

Importing the certificate can make a browser require HTTPS at every localhost address

Keycloak tells a browser that trusts its certificate to use HTTPS for every localhost address, on every port, for a year. In Chromium on Linux with the file imported, signing in can then end in a secure connection error, after which Quine Enterprise, Grafana, Prometheus and the reverse proxy no longer open at localhost. Accepting the warning on the sign-in page, instead of importing the file, avoids this. If it happens, either:

  • Use local hostnames. Give everything its own name; see Local Hostnames. This works with both products and with the reverse proxy.
  • Use 127.0.0.1. Open http://127.0.0.1:8080 and http://127.0.0.1:3000 in place of localhost. With both products running, open both there. They then share a session cookie, so a product you go back to may sign you in again. With the reverse proxy, signing in returns to localhost from any address, so serve the proxy over HTTPS with tls: true; see Reverse Proxy.

The certificate authority is valid for ten years. About 13 months before it expires, or if its files can't be read, quinectl makes a new one. When that happens, run quinectl trust again. Keycloak's own certificate is renewed about every 13 months from the same certificate authority, so that renewal needs no new trust.

Two products, two addresses

When Quine Enterprise and Novelty both have auth on, they must be opened at different host names. Both products use the same session cookie name, and browsers don't separate cookies by port, so signing in to one would sign you out of the other. quinectl serves one on localhost and the other on 127.0.0.1, and up prints which is which:

→ browser sessions: quine at http://localhost:8080, novelty at http://127.0.0.1:8090 — both products set the same session cookie name, and cookies ignore ports, so use one host alias per product

Open each product at the address on that line.

For addresses that are easier to tell apart, give each product its own name; see Local Hostnames. Instead of http://localhost:8080 and http://127.0.0.1:8090, you open http://quine.localhost:8080 and http://novelty.localhost:8090, and you still stay signed in to both.

Turning auth off

Set services.auth: none. Then remove the auth fields from the product blocks, because quinectl refuses them without Keycloak: realm, clientId, accessTokenAudience, roles, seedTestUsers and users. A file written by quinectl init --agent always sets realm for each product, so remove those lines too. A field left in stops up with an error like this one:

error: loading ./quinectl.yaml: quine.realm is used only under services.auth: keycloak -- remove it or set services.auth: keycloak — see 'quinectl generate-config' for a complete commented example

Using an existing Keycloak

To use a Keycloak you already run instead of starting one, give quinectl its admin API and an admin account:

quinectl.yaml
quine:
  edition: enterprise
  licenseKey: ${QE_LICENSE_KEY}
  customerId: ${QE_CUSTOMER_ID}
services:
  persistor: cassandra
  auth:
    keycloak:
      external:
        adminURL: https://keycloak.example.com
        adminUser: ${KEYCLOAK_ADMIN}
        adminPassword: ${KEYCLOAK_ADMIN_PASSWORD}
  proxy: none
  metrics: none
  kafka: none

quinectl creates the realm, client and roles it needs there, and never starts, stops or removes that Keycloak. Set manageRealm: false to have it only read what is already configured. It never creates or changes users in an external Keycloak. A users list is ignored, and quinectl token is refused, so get tokens from that Keycloak yourself.

Next steps

  • Run Novelty with its own realm beside Quine Enterprise: Run Novelty.
  • Give each project its own realm and users: Multi-tenancy.