@cto.ai/ops-keycloak
CTO.ai Keycloak library
Straightforward Keycloak integration.
API
This is a native ESM module.
keycloak(opts) => instance
Options:
realm
- the keycloak realm nameurl
- the keycloak server URLid
- client idpages
- an object that must contain the following properties: signup
, signin
, error
. Each must hold a Buffer
instance, containin HTML to redirect a users browser after a user has registered, logged in or if there was an error, respectively.backend
default: false
- backend mode limited API. Only functionality that doesn't rely on client-side browser interactions is supplied: refresh
, signout
and signin
, where signin
must be passed user and password. Pages are not required when backend
is true
.
Tokens objects:
Much of the API either accepts or outputs tokens
. A tokens object has the following shape:
{
accessToken: string
refreshToken: string
idToken: string
sessionState: string
}
instance.signup() => Promise => tokens
Opens the default browser to the registration URL and supplies tokens
once the registration process has been completed in the browser.
instance.signin(opts) => Promise => tokens
Triggers a browser-based login flow or logs in with a given username and password.
If both user
and password
options are supplied these credentials will be
exchanged for tokens
. Otherwise, opens the default browser to the login URL and supplies tokens
when the login process has been completed in the browser.
Options:
user
Optional - usernamepassword
Optional - password
instance.refresh(tokens) => Promise => tokens
Accepts a tokens
object and fetches fresh tokens
.
instance.signout(tokens) => Promise
Invalidates the tokens
passed.
instance.reset(opts)
Will open a browser at a Keycloak password reset URL, which differs based on the signedIn
options.
Options:
signedIn
(boolean
), Default: false
- If true
the browser will open to the logged-in accounts password page. If false
it will open to reset credentials page.
instance.teams(tokens) => Promise => [teams]
Returns a promise that resolves the teams for the user that the tokens belong to.
instance.validate(tokens) => boolean
See keycloak.validate
instance.identity(tokens) => { id, username, email }
See keycloak.identity
keycloak.validate(tokens) => boolean
Checks whether tokens.refreshToken
has expired. If it has validate
returns true
, otherwise false
.
If any tokens are missing from the tokens
object, this function will throw.
keycloak.identity(tokens) => { id, username, email }
Decodes tokens.idToken
and returns an object with a users id
, username
and email
.
Caveats
This library does not attempt to provide anything close to full Keycloak functionality integration.
Engines
Development
Test:
npm test
Visual coverage report (run after test):
npm run cov
Lint:
npm run lint
Autoformat:
npm run lint -- --fix
Releasing
For mainline releases:
npm version <major|minor|patch>
git push --follow-tags
For prereleases:
npm version prerelease
git push --follow-tags
License
MIT