Skip to content

Authentication and Security

Overview

The Jaxon platform uses Authentik as its identity provider for all authentication and authorization. Authentik provides OAuth2/OIDC-based single sign-on and user management through a dedicated admin portal.

Logging In

  1. Navigate to the platform URL in a browser.
  2. The browser redirects to the Authentik login page.
  3. Enter credentials and complete the login flow.
  4. Once authenticated, the browser redirects back to the platform with the session active.

Sessions expire automatically after a configured period. When this happens, the browser redirects to the login page again.

Security Groups

Access within the platform is organized by Authentik security groups. Groups function as teams -- they own assets at a project level. Users can belong to one or more groups, and platform resources (documents, rulesets, datasets, runs) are scoped to the group that created them.

Groups are not tied to fixed permission levels. Organizations define groups based on team structure (e.g., by department, project, or compliance area). The X-Jaxon-Active-Group header in API requests determines which group context is active for a given operation.

API Authentication

The REST API supports two authentication methods, depending on the context:

Jaxon UI (browser-based)

The Jaxon web application authenticates users via OAuth 2.0 Authorization Code with PKCE. When a user logs in through the UI, the browser performs the PKCE flow against Authentik to obtain an access token. The UI then includes this token in all API requests on behalf of the logged-in user. This flow is handled automatically by the UI and requires no manual configuration.

Standalone API Access (programmatic)

For programmatic or service-to-service access outside the UI, a platform administrator creates a service account in Authentik, assigns it to the appropriate groups, and creates an API token. The API token can be used directly as a Bearer token in API requests along with the X-Jaxon-Active-Group header. No token exchange is required. See API Reference for curl examples and required headers.

Administrator Access

Administrators manage users, groups, and security configuration through the Authentik admin portal at <host>/if/admin/.

Administrators are responsible for:

  • Creating and maintaining user accounts
  • Creating and managing security groups
  • Assigning users to groups
  • Managing service accounts for automation
  • Configuring authentication policies

Managing Users

  1. Log in to the Authentik admin portal.
  2. Navigate to Directory > Users.
  3. Click Create to add a new user, or select an existing user to modify.

Managing Groups

All operational groups are children of the Jaxon Platform parent group. This parent-group hierarchy controls who can log in to the application — any user in a child group of "Jaxon Platform" is granted access automatically.

To create a new group:

  1. Navigate to Directory > Groups.
  2. Click Create.
  3. Enter the group name.
  4. Set Parent to Jaxon Platform.
  5. Click Create to save.

Users assigned to the new group can log in immediately — no policy changes are required.

To manage members of an existing group:

  1. Navigate to Directory > Groups and select the group.
  2. Under the Members tab, add or remove users.

Creating a Service Account and API Token

Service accounts provide programmatic access to the platform API for automation, CI/CD pipelines, and service-to-service integrations. Unlike regular user accounts, service accounts are not intended for interactive login.

Step 1: Create the service account

  1. Log in to the Authentik admin portal at <host>/if/admin/.
  2. Navigate to Directory > Users.
  3. Click Create Service Account.
  4. Enter a Username (e.g., svc-my-integration).
  5. Leave Create group unchecked (this creates an Authentik-level group for the service account itself, which is unrelated to Jaxon platform groups).
  6. Click Create.

The service account appears in the user list with a path of goauthentik.io/service-accounts.

Step 2: Assign the service account to a platform group

Like any user, the service account must belong to at least one Jaxon platform group to access platform resources.

Service accounts do not appear in the default user list — Authentik stores them under a separate path. The easiest way to assign group membership is from the group side:

  1. Navigate to Directory > Groups and select the target group (e.g., "Jaxon Users").
  2. Select the Users tab.
  3. Click Add existing user and search for the service account username (e.g., svc-my-integration). The search will find service accounts even though they are hidden from the main user list.
  4. Click Add to confirm.

Step 3: Create an API token

  1. Navigate to Directory > Tokens and App passwords.
  2. Click Create.
  3. Fill in the token details:
    • Identifier: A unique name for the token (e.g., svc-my-integration-api).
    • User: Select the service account created in Step 1.
    • Intent: Select API.
    • Expiring: Uncheck this for long-lived automation tokens, or leave checked and set a date for time-limited access.
  4. Click Create.
  5. Back on the token list, click the copy icon next to the new token to copy the token key. Store this value securely -- it will not be shown again in full.

Step 4: Test the token

Verify the token works by making an API request:

curl -sk https://<host>/api/v1/projects \
  -H "Authorization: Bearer <token-key>" \
  -H "X-Jaxon-Active-Group: <group-name>"

A successful response returns JSON with an HTTP 200 status -- for example, a list of projects (which may be empty for a new service account):

[]

Common errors:

Symptom Cause
HTML page with 302 Found The request is hitting the wrong URL path or the Authorization header is missing. The API path is /api/v1/... (not /platform-api/api/v1/...). Requests to unrecognized paths fall through to the UI, which redirects unauthenticated users to the login page.
401 Unauthorized The token key is incorrect, or the token was created with the wrong Intent (must be API).
403 Forbidden The service account is not a member of the group specified in X-Jaxon-Active-Group.

See API Reference for the full list of required headers and available endpoints.

Assigning Users to Groups

Every user (including service accounts) must be assigned to at least one group before they can use the platform. The X-Jaxon-Active-Group header is required on all API requests, and the UI provides a group dropdown where the active group can be selected. The dropdown defaults to the first group in alphabetical order. A user without any group membership cannot access any platform functionality.

Group membership determines which assets are visible and accessible. Documents, rulesets, datasets, runs, and other resources are scoped to the group that created them. A user only sees assets belonging to the currently active group.

The auditor group is a special case. Members of the auditor group have read-only access to the activity log across all groups, enabling compliance review and audit oversight without requiring membership in each individual group.

To assign a user to a group:

  1. Log in to the Authentik admin portal.
  2. Navigate to Directory > Groups and select the target group.
  3. Select the Members tab.
  4. Click Add existing user and search for the user to add.
  5. Click Add to confirm.

Alternatively, from the user side:

  1. Navigate to Directory > Users and select the user.
  2. Select the Groups tab.
  3. Click Add to existing group and select the target group.

Changes take effect immediately. Users may need to log out and back in to refresh group memberships.