Authentication #

Kuzzle PaaS uses Kuzzle authentication. In deployments configured with Keycloak, users authenticate with the keycloak strategy and then use the returned Kuzzle JWT for subsequent API calls.

Login with Keycloak #

Start a Keycloak login:

const response = await kuzzle.query(
  {
    controller: 'auth',
    action: 'login',
    strategy: 'keycloak',
    body: {
      redirectUri: 'https://your-client.example.com/callback'
    }
  },
  {
    queuable: false,
    timeout: -1,
    verb: 'POST'
  }
);

The API returns the Keycloak session identifier in the keycloak response header and the identity-provider URL in the location response header.

After the identity provider redirects back to your callback URL, complete the login:

const response = await kuzzle.query({
  controller: 'auth',
  action: 'login',
  strategy: 'keycloak',
  body: {
    sessionId: '<keycloak-session-id>',
    callbackUrl: 'https://your-client.example.com/callback?code=...&state=...'
  }
});

const { jwt, expiresAt } = response.result;
kuzzle.jwt = jwt;

Refresh a token #

const response = await kuzzle.query({
  controller: 'auth',
  action: 'refreshToken',
  strategy: 'keycloak',
  sessionId: '<keycloak-session-id>',
  body: {
    sessionId: '<keycloak-session-id>'
  }
});

const { jwt, expiresAt } = response.result;
kuzzle.jwt = jwt;

Check the current user #

const token = await kuzzle.auth.checkToken(jwt);

if (token.valid) {
  kuzzle.jwt = jwt;
  const user = await kuzzle.auth.getCurrentUser();
}

Get a Keycloak logout URL #

Use this endpoint when your integration needs to redirect a user to Keycloak logout.

const logoutUrl = await kuzzle.query({
  controller: 'sso',
  action: 'getLogoutUrl',
  redirect_uri: 'https://your-client.example.com/login'
});

HTTP route:

GET /_/sso/logout-url?redirect_uri=https%3A%2F%2Fyour-client.example.com%2Flogin

Response:

"https://<issuer>/protocol/openid-connect/logout?client_id=<client-id>&post_logout_redirect_uri=..."

Authorization #

Access is scoped by organization membership. Organization, project, environment, application, release, deployment, monitoring and alerting actions require an authenticated user who is a member of the target organization and, for project-scoped resources, attached to the target project. Organization owners and admins reach every project of their organization without being attached to it.

Within an organization, members hold one of four roles:

The exact action list of each role is enforced by Kuzzle security roles; each page of this section states when an action needs more than member.

Some actions are reserved to platform administrators: creating an organization (unless the platform enables self-service organization creation), migrating a legacy project into an organization (organization:importProject), and reconciling the project Kubernetes access (organization:checkProjectsK8sAccess, organization:alignProjectsK8sAccess).