Authenticate Users #

Kuzzle's authentication system is multi-strategy based. This means that the same user can authenticate in several different ways.

For example, the same user can authenticate with the local strategy with an username and a password pair but also with the oauth strategy using an external provider such as Facebook or Google.

Kuzzle uses Passport.js under the hood, and therefore there are 300+ strategies readily available. (LDAP, OpenID, Active Directory, x509, etc.)

We saw that in the Set Up Permission guide, when creating a user, we had to provide credentials for the local strategy, but we could have provided more strategies (provided the right strategy plugins are used):

{
  // User profiles
  content: {
    profileIds: ["dummy"]
  },

  // User credentials
  credentials: {

    // User will be able to login with the "local" strategy
    local: {
      username: "najada",
      password: "password"
    },

    // User will be able to login with the "ldap" strategy
    ldap: {
      bindDN: "cn=root",
      searchBase: "ou=passport-ldapauth",
      searchFilter: "(uid=najada)"
    }
  }
}

New authentication strategies are made available by authentication plugins.

By default, only the local strategy is available.

We also provide an authentication plugin for the OAuth strategy but it's not available by default and need to be added to your application.

Getting an authentication token #

Kuzzle uses authentication tokens to identify user sessions.

First we need to get one with the auth:login action. This action takes the strategy used as a mean to authenticate, and any additional information needed by that strategy.

In our example we will use the local strategy so we have to provide a username and a password:

We previously created a user with the username melis and the password password. If you don't have this user, you can create it with the following command:

kourou security:createUser '{
  content: {
    profileIds: ["default"]
  },
  credentials: {
    local: {
      username: "melis",
      password: "password"
    }
  }
}'

Then we can log in with the following command:

Using API #

curl -XPOST 'http://localhost:7512/_login/local' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "melis",
  "password": "password"
}'

## Response
{
  "action": "login",
  "controller": "auth",
  "error": null,
  "headers": {},
  "node": "knode-glamorous-flaubert-1113",
  "requestId": "688feaf7-d720-4d23-9ba6-cc43487f0108",
  "result": {
    "_id": "kuid-tricky-comedian-10492",
    "expiresAt": 1729776561843,
    "jwt": "kauth-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJrdWlkLXRyaWNreS1jb21lZGlhbi0xMDQ5MiIsImlhdCI6MTcyOTc3Mjk2MSwiZXhwIjoxNzI5Nzc2NTYxfQ.m_c8h3aLxqOa45afgFgowRnQ5f4uSPG3QVKDW1taYak",
    "ttl": 3600000
  },
  "status": 200,
  "volatile": null
}

Using CLI #

kourou auth:login -a strategy=local --body '{
  username: "melis",
  password: "password"
}'

## Response
[ℹ] Unknown command "auth:login", fallback to API action

 🚀 Kourou - Executes an API query.

 [ℹ] Connecting to ws://localhost:7512 ...
{
  "_id": "kuid-tricky-comedian-10492",
  "expiresAt": 1729776399610,
  "jwt": "kauth-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiJrdWlkLXRyaWNreS1jb21lZGlhbi0xMDQ5MiIsImlhdCI6MTcyOTc3Mjc5OSwiZXhwIjoxNzI5Nzc2Mzk5fQ.9rBVc4h6hV3Rsb0Z6kvLKhlZNxI-9O7xeWJnC6LfCEQ",
  "ttl": 3600000
}
 [✔] Successfully executed "auth:login"

Kuzzle sent us back the token in the jwt property

Usually, login attempts are made by anonymous users, to acquire a token granting the necessary rights to perform more actions.

Since removing rights to the auth:login action from anonymous users would mean that it would be no longer possible to log in, Kuzzle prevents that action from ever be removed from the anonymous role.

Using an authentication token #

Now that we have a token, we must pass it to API requests, either in the HTTP headers or in the Kuzzle request payload, depending on what network protocol is used.

When using Kourou with --username and --password flags, the auth:login action is called and the received token is automatically used along with subsequent requests.

Using API #

curl -H "Authorization: Bearer <token>" http://localhost:7512/_me

Using CLI #

kourou auth:getCurrentUser -a jwt=<token>

Using Websocket #

npx wscat -c ws://localhost:7512 --execute '{
  "controller": "auth",
  "action": "getCurrentUser",
  "jwt": "<token>"
}'

Using javascript SDK #

kourou sdk:execute '
  sdk.jwt = "<token>";
  console.log(await sdk.auth.getCurrentUser());
'

Kourou is able to execute Javascript code snippets.
A sdk variable is exposed and refers to an instance of the Javascript SDK, connected to Kuzzle and authenticated if credentials are provided.

◄ Set up PermissionsSubscribe to Realtime Notifications ►

Edit this page on Github