Skip to main content

Configure the Navin Platform for the first time

This page takes a new installation to a working platform: first administrator, tenants, administrators of each tenant and single sign on with Keycloak (with LDAP or Active Directory behind it). It is done by the platform administrator (role platform_admin).

Before you begin​

  • The installation is verified: GET /readyz answers ready (Verify).
  • The installation password of the first administrator:
    • OS packages: sudo grep '^EAI_BOOTSTRAP_ADMIN_PASSWORD=' /etc/navin-platform/platform.env;
    • Docker Compose and make: EAI_BOOTSTRAP_ADMIN_PASSWORD of deploy/compose/.env or local.env;
    • Kubernetes: put EAI_BOOTSTRAP_ADMIN_USERNAME and EAI_BOOTSTRAP_ADMIN_PASSWORD in the secret of the Control Plane for the first sign in only.

Steps​

  1. Sign in with the installation account. The API creates the account at startup when it does not exist, with the roles platform_admin and tenant_admin on the tenant EAI_BOOTSTRAP_TENANT (default). Open the portal, tab Login, and sign in.

    Expected result: the portal asks for a new password (12 characters minimum by default, EAI_LOCAL_PASSWORD_MIN_LENGTH). The installation password stops working.

    If it fails: account_locked after 5 wrong passwords (EAI_LOCAL_AUTH_MAX_FAILURES), wait 15 minutes (EAI_LOCAL_AUTH_LOCKOUT_SECONDS).

    warning

    In production the API refuses a weak installation password (navin, the login, fewer than 12 characters, no letters and digits). Remove EAI_BOOTSTRAP_ADMIN_PASSWORD from the settings once the first administrator has chosen a password: a later start never resets the account.

  2. Create the tenants. A tenant (organisation) isolates data, policies, budgets and audit trail (row level security in PostgreSQL). Create one per entity of the bank, in the portal or with the API:

    TOKEN=$(curl -fsS <control-plane-url>/v1/auth/login -H 'Content-Type: application/json' \
      -d '{"username": "navin", "password": "<password>"}' | jq -r .token)
    curl -fsS <control-plane-url>/v1/tenants -H "Authorization: Bearer $TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"slug": "retail", "name": "Retail banking", "data_residency": "eu", "admins": []}'

    slug: lowercase letters, digits and -, 2 to 63 characters. admins: subjects (OIDC sub) given tenant_admin.

    Expected result: 201 with the tenant; GET /v1/tenants lists it.

    If it fails: 409 when the slug exists; 403 without platform_admin.

  3. Connect Keycloak. The API validates the tokens of the realm; the portal redirects to it (authorization code with PKCE, public client portal, redirect URI <portal URL>/auth/callback). The realm deploy/keycloak/realm-enterprise-ai.json declares the clients portal, control-plane and cli, the realm roles and the groups navin-platform-admins and navin-admins-default.

    Settings of the API (packages: platform.env; Kubernetes: controlPlane.config):

    EAI_OIDC_ISSUER='https://<keycloak-host>/realms/enterprise-ai'
    EAI_OIDC_AUDIENCE='<audience>'
    EAI_OIDC_JWKS_URL='https://<keycloak-host>/realms/enterprise-ai/protocol/openid-connect/certs'

    Settings of the portal: NEXT_PUBLIC_EAI_OIDC_ISSUER (or NEXT_PUBLIC_OIDC_ISSUER) and NEXT_PUBLIC_EAI_OIDC_CLIENT_ID (or NEXT_PUBLIC_OIDC_CLIENT_ID, default portal).

    <audience>: the audience the tokens of your realm carry; the Helm values use control-plane, the client of the API in the realm.

    Expected result: the sign in page shows Sign in with SSO and a Keycloak user reaches the portal.

    If it fails: a 401 with a valid Keycloak session means a wrong audience or issuer; compare with the iss and aud claims of the token.

  4. Federate the directory. Keycloak reads LDAP or Active Directory read only and imports its groups; the API receives them in the claims groups and entra_groups and applies the mappings at each sign in (EAI_OIDC_GROUP_SYNC). The administrators come from the groups:

    GroupRole given
    navin-platform-admins (EAI_OIDC_PLATFORM_ADMIN_GROUPS)platform_admin
    navin-admins-<tenant slug> (EAI_OIDC_TENANT_ADMIN_GROUP_PREFIX)tenant_admin of that tenant

    Names are compared without case. To keep the names of your directory, change the two settings.

    Expected result: a member of navin-admins-retail signs in as tenant_admin of retail.

  5. Turn the local sign in off. Once SSO works for at least two administrators:

    EAI_LOCAL_AUTH_ENABLED='false'

    Expected result: POST /v1/auth/login answers 403 local_auth_disabled.

  6. Activate the licence. The portal screen Licences, or POST /v1/license/activations; the public keys of the publisher are EAI_LICENSE_PUBLIC_KEYS. See Licensing.

Verify​

curl -fsS <control-plane-url>/v1/identity/whoami -H "Authorization: Bearer <token>"

<token>: access token of a Keycloak user. Expected output: the subject, its tenant and its roles.

Next steps​

Troubleshooting​

SymptomCauseFix
tenant_suspended at sign inTenant status is suspendedPATCH /v1/tenants/{tenant_id} with {"status": "active"}
A directory administrator has no roleGroup name differsRename the group or change EAI_OIDC_*_ADMIN_*
Administrator of several tenants lands on noneToken without tenant claimSet the Keycloak attribute tenant of the user