Core
PaaS v2.x
2

Access private packages #

Licensed Kuzzle JavaScript packages (@kuzzleio/*) are distributed through the private package registry hosted by Kuzzle PaaS, at https://packages.paas.kuzzle.io.

You authenticate to it with a scoped API key: a Kuzzle API key bound to one identity and one project of your organization. Each use of the key is recorded in the project's registry-access trail, which any project member can read (org-apikey:listAccess).

In a CI/CD pipeline #

When an organization owner or admin generates the deployment credentials of an environment (org-environment:generateGithubDeploymentCredentials, the credentials button of the environment view), the console issues a scoped API key to the organization's ci machine identity and stores it in the project's GitHub repository as two repository secrets:

  • PAAS_ROBOT_USERNAME: the identity the key belongs to;
  • PAAS_ROBOT_APIKEY: the key itself.

Generating the credentials again issues a new key, stores it, then revokes the previous one.

Write the .npmrc from these secrets in your workflow, before installing dependencies. See Configure npm for the format, and Continuous deployment for the complete pipeline.

For a developer #

A developer gets their own scoped API key, issued by an organization owner or admin — a member never issues a key to themself. The key is shown once, in the response that creates it: the person who issues it hands it over to the developer.

const apiKey = await kuzzle.query({
  controller: 'org-apikey',
  action: 'create',
  organizationId: 'paas-org-my-company',
  projectId: 'my-project',
  label: 'john-doe-laptop',
  identityId: 'kuid-john-doe'
});
// apiKey.token is the secret, apiKey.apiKeyId identifies the key

identityId is the identity the key is issued to: a member's user id, or a machine identity. It defaults to the caller. The project a key is bound to is what its uses are recorded under. Revoke a key that is no longer needed with org-apikey:revoke.

Configure npm #

npm sends the key as a password: put it in _password, base64-encoded, along with the identity as username. A key set as _authToken is refused by the registry.

cat >> ~/.npmrc <<EOF
@kuzzleio:registry=https://packages.paas.kuzzle.io/
//packages.paas.kuzzle.io/:username=<identity>
//packages.paas.kuzzle.io/:_password=$(printf '%s' '<api key>' | base64 | tr -d '\n')
EOF

In a pipeline, write the project's .npmrc instead, from PAAS_ROBOT_USERNAME and PAAS_ROBOT_APIKEY.

You can then install private packages:

npm install @kuzzleio/<kuzzle-plugin>

See the official plugin list for available Kuzzle plugins.

Login and password (deprecated) #

Before scoped API keys, the registry was accessed with Kuzzle PaaS account credentials, through npm login --scope=@kuzzleio --registry=https://packages.paas.kuzzle.io --auth-type=legacy or kourou paas:login, and pipelines used kuzzleio/paas-action to do the same. This access is deprecated: it is still accepted while the last users move to scoped API keys, and will then be removed. Switch to a scoped API key.

A revoked API key is refused outright: it never falls back to login and password.

What's next? #

Once private packages are available, see Continuous deployment to release and deploy your project from the console, and the public API to automate it.

Community #