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:
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:
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:
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 analyst1picks another. A name that isn't one of the configured users is refused with the list of valid ones. - With both products running,
--product noveltysigns in to Novelty's realm. - Tokens expire after five minutes (
expiresIn: 300inquinectl token --json). Callquinectl tokeninside 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 oflocalhost. 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 tolocalhostfrom any address, so serve the proxy over HTTPS withtls: 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:
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.