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, monitoring and alerting endpoints require an authenticated user who is a member of the target organization and, for project-scoped resources, attached to the target project.

Within an organization, members hold a role — owner, admin or member. Mutating actions (creating or deleting projects, managing members, configuring alerts, issuing API keys) require an owner or admin role; members have read access to the resources they are attached to.

Some administrative actions (for example migrating a legacy project into an organization) are reserved to platform administrators and configured in Kuzzle security profiles.