Skip to content

authentication.md

Latest commit

 

History

History
277 lines (209 loc) · 10.2 KB

authentication.md

File metadata and controls

277 lines (209 loc) · 10.2 KB
Raw
title Authentication
sidebar
order
2

datumctl uses OAuth 2.0 and OpenID Connect (OIDC) with the PKCE extension for secure authentication against Datum Cloud. This avoids the need to handle static API keys directly.

Authentication involves the following commands:

  • datumctl login
  • datumctl logout
  • datumctl whoami
  • datumctl auth list
  • datumctl auth get-token
  • datumctl auth update-kubeconfig
  • datumctl auth switch

Credentials and tokens are stored securely in your operating system's default keyring.

Logging in

To authenticate with Datum Cloud, use the login command:

datumctl login [--hostname <auth-hostname>] [--no-browser] [--credentials <file>] [--project <project> | --organization <org>] [-v]
  • --hostname <auth-hostname>: (Optional) Specify the hostname of the Datum Cloud authentication server. Defaults to auth.datum.net.
  • --no-browser: (Optional) Do not attempt to open a browser; print the login URL and use the device authorization flow (enter a user code) so you can complete login without a local callback.
  • --credentials <file>: (Optional) Sign in as a service account using its credentials JSON file. Non-interactive; see Service accounts.
  • --project <project> / --organization <org>: (Optional) The context to switch to after signing in, instead of choosing one in the picker. A project can be given as <org>/<project>. DATUM_PROJECT and DATUM_ORGANIZATION work the same way when neither flag is set.
  • -v, --verbose: (Optional) Print the full ID token claims after successful login.

Running this command will:

  1. Attempt to open your default web browser to the Datum Cloud authentication page (or use device authorization if --no-browser is used).
  2. If the browser cannot be opened automatically, it will print a URL for you to visit manually.
  3. Authenticate via the web page (this might involve entering your username/password or using single sign-on).
  4. After successful authentication, you will be redirected back to datumctl (via a local webserver started temporarily), which completes the process.

Your credentials (including refresh tokens) are stored securely in the system keyring, associated with your user identifier (typically your email address).

Choosing a context

After signing in, datumctl login switches to a default context:

  • With --project, --organization, DATUM_PROJECT or DATUM_ORGANIZATION, it switches to that context. If none of your organizations or projects match, login keeps the session and exits with an error naming the value.
  • With a single organization and no projects, it switches to that one.
  • Otherwise it shows a picker. The picker needs an interactive terminal. Without one (a coding agent's shell, a script), login still signs you in and saves the session, but leaves the context unset. Choose one afterwards with datumctl ctx use <org>/<project>; datumctl ctx lists them.

Service accounts (CI and automation)

A service account is a non-human identity for CI pipelines, scheduled jobs, and other automation. It signs in with a credentials file instead of a browser, so there are no prompts and no human account involved.

Getting a credentials file

Create the service account in the Datum Cloud portal (for staging, https://cloud.staging.env.datum.net) and download its credentials JSON file. The file has "type": "datum_service_account" and carries the account's client_id, client_email, and an RSA private key. Treat it as a secret: store it in your CI provider's secret store and write it to disk only on the runner.

The same file works against any environment; --hostname picks which one. Human accounts cannot use this path.

Signing in

datumctl login --credentials ./key.json

For staging:

datumctl login --credentials ./key.json --hostname auth.staging.env.datum.net

datumctl exchanges a signed JWT for an access token and stores the session in the keyring. The private key is kept on disk under your user config directory (datumctl/service-accounts/) so the token can be renewed without the original file. There is no refresh token: when the access token expires, datumctl mints a new JWT and exchanges it again automatically, for as long as the key stays valid.

On a CI runner with no system keyring, datumctl falls back to a plain file at ~/.datumctl/credentials.json (mode 0600) and prints a warning at login. Treat that file like the credentials file itself.

Choosing a scope

In CI there is no terminal for the context picker, so set the scope on each command with DATUM_PROJECT or DATUM_ORGANIZATION (or the --project / --organization flags):

DATUM_PROJECT=my-project datumctl diff -f manifest.yaml
DATUM_PROJECT=my-project datumctl apply -f manifest.yaml
DATUM_ORGANIZATION=my-org datumctl get projects

If the service account can see exactly one organization or project, login selects it as the context automatically. If it can see more, login in a non-interactive shell reports that context selection needs a terminal; the session is still signed in, and scoping each command as above is the supported pattern.

How the session appears

The session is listed like any other, under the account's client_email:

$ datumctl auth list
User              Status
<client_email>    Active

datumctl ctx lists the organizations and projects the service account can reach, and datumctl whoami shows the account's identity and the effective scope. The service account must have access to the target organization, and that organization must have completed onboarding (see below). To remove the session, run datumctl logout <client_email>.

Account onboarding

Before you can use datumctl against an organization, that organization must complete onboarding in the Datum Cloud portal. This includes finishing billing setup (contact information, billing account, and payment method).

Onboarding is checked per organization, based on your active context or --organization / --project flags. User-scoped discovery commands such as datumctl get organizations always run against your user control plane, even when your active context points at an incomplete organization. That command also shows each organization's setup status and portal links for any that still need setup.

When the targeted organization is incomplete:

  • datumctl login stores your credentials but blocks selecting that organization's context and prints a link to the portal.
  • Org- or project-scoped commands are blocked with a message pointing you to the portal.
  • datumctl whoami shows onboarding status for your current context's organization.

Machine accounts are subject to the same requirement for the organization they target.

For staging environments, use the staging portal at https://cloud.staging.env.datum.net.

Updating kubeconfig

Once logged in, you typically need to configure kubectl to authenticate to Datum Cloud Kubernetes clusters using your datumctl login session. Use the update-kubeconfig command:

datumctl auth update-kubeconfig [--kubeconfig <path>] [--project <name>] [--organization <name>]
  • --kubeconfig <path>: (Optional) Path to the kubeconfig file to update. Defaults to the standard location ($HOME/.kube/config or the path specified by the KUBECONFIG environment variable).
  • --project <name>: Specify the Datum Cloud project name to configure access for. You can find project IDs after creating projects in Datum Cloud.
  • --organization <name>: Specify the Datum Cloud organization name to configure access for. You can find your organization ID using datumctl organizations list.

Important

You must specify either --project or --organization.

This command adds or updates the necessary cluster, user, and context entries in your kubeconfig file. The user entry will be configured to use datumctl auth get-token --output=client.authentication.k8s.io/v1 as an exec credential plugin. This means kubectl commands targeting this cluster will automatically use your active datumctl login session for authentication.

Listing logged-in users

To see which users you have authenticated locally, use the list command:

datumctl auth list
# Alias: datumctl auth ls

This will output a table showing the Name, Email, and Status (Active or blank) for each set of stored credentials. The user marked Active is the one whose credentials will be used by default for other datumctl commands and kubectl (if configured via update-kubeconfig).

Switching active user

If you have logged in with multiple user accounts (visible via datumctl auth list), you can switch which account is active using the switch command:

datumctl auth switch <user-email>

Replace <user-email> with the email address of the user you want to make active. This user must already be logged in.

After switching, subsequent commands that require authentication (like datumctl organizations list or kubectl operations configured via update-kubeconfig) will use the credentials of the newly activated user.

Logging out

To remove stored credentials, use the logout command.

Log out a specific user:

datumctl logout <user-email>

Replace <user-email> with the email address shown in the datumctl auth list command.

Log out all users:

datumctl logout --all

This removes all Datum Cloud credentials stored by datumctl in your keyring.

Getting tokens (advanced)

The get-token command retrieves the current access token for the active authenticated user. This is primarily used internally by other tools (like kubectl) but can be used directly if needed.

datumctl auth get-token [-o <format>]
  • -o, --output <format>: (Optional) Specify the output format. Defaults to token.
    • token: Prints the raw access token to standard output.
    • client.authentication.k8s.io/v1: Prints a Kubernetes ExecCredential JSON object containing the ID token, suitable for kubectl authentication.

If the stored access token is expired, get-token will attempt to use the refresh token to obtain a new one automatically.