Federated Authentication with Okta

Federated Authentication with Okta in Lightbits clusters allows you to use your existing Okta tenant as the identity provider (IdP) for management-plane authentication. This capability eliminates the need to manage local users on the Lightbits system, and provides seamless integration with your Okta organization.

Authentication is performed via OAuth 2.0 / OIDC. A user authenticates to Okta once, and subsequent Lightbits CLI (lbcli) commands carry the Okta-issued authorization token (JWT), which the cluster verifies and maps to Lightbits roles.

Lightbits Okta integration supports:

• Device Authorization Flow: User mode - for users interacting directly with the Lightbits cluster using the Lightbits CLI utility.

High-Level Okta Workflow

This section details the high-level workflow for using Okta.

Implementing this feature consists of two main steps:

1. Initial configurations on the Lightbits cluster, supported by the dedicated Lightbits APIs:

• Configure information describing the Okta authorization server (the IdP).

• Configure information of IdP client configurations.

• Create mapping table entries of Okta groups to Lightbits’ scope and role (referred to as AuthMap).

2. On the user’s client machine:

• Prepare a configuration file for the lbcli utility, with information on the IdP.

Once the configurations are set, you can use the Lightbits CLI to log in using Okta. You can then get services from the Lightbits cluster based on your predefined role.

This document describes the configuration steps, as well as the relevant APIs and lbcli support.

Prerequisites: Okta-Side Configuration

Before configuring the cluster, an Okta administrator must set up an application and authorization server, and hand a few values to the Lightbits cluster admin.

In your Okta tenant:

1. Create a Native OIDC application (Applications → Applications → Create App Integration → OIDC - OpenID Connect → Native Application). In the application, enable the Device Authorization grant type, and confirm Client authentication = None (a public client — no client secret is issued for the device flow). Note the Client ID.

2. Assign the application to the users and/or groups that should be allowed to log in (Assignments).

3. Choose an authorization server (Security → API → Authorization Servers) — the pre-provisioned default server or a dedicated one — and note its Issuer URI; e.g., https://<org>.okta.com/oauth2/<auth-server>.

4. Add a groups claim to the access token (Authorization Server → Claims → Add Claim): name groups, include in the Access Token, value type Groups, with a filter that matches the group names you want to appear in the token. The cluster uses this claim to map group membership to Lightbits roles.

5. Allow the device-flow grant in an access policy (Authorization Server → Access Policies): The policy rule must apply to the Native OIDC application created in step 1 (the default policy applies to all clients; a dedicated policy must assign this client), permit the Device Authorization grant type, and include the openid scope. If the rule does not cover this client, grant type, and scope, Okta’s token endpoint will refuse the device-code grant.

Hand off to the Lightbits cluster admin: the Client ID, the Issuer URI, and the scope (typically openid).

Configuring the Authentication Feature on the Lightbits Cluster

You can configure the authentication feature either by using the REST API or with lbcli. The following section details both options.

• The cluster’s machines must have network connectivity to the Okta authorization server (directly or via the optional proxy configured in Step 1).

• Running these configuration commands requires an initial valid JWT with cluster/admin scope/role permissions. See the Lightbits lbcli and REST documentation for additional information.

Step 1: Create the IdP Configuration

The Okta issuer URL must be the exact authorization-server Issuer URI as shown in Okta (Security → API → Authorization Servers). For example: https://<org>.okta.com/oauth2/<auth-server> (the default server is .../oauth2/default), or your Okta custom-domain equivalent (e.g. https://login.<company>.com/oauth2/<auth-server>).

Do not use the bare org URL.

CLI

REST — POST _api_v2_cluster_IdpConfiguration

Fields:

• name - The IdP configuration name of your choice (required).

• type - The IdP type. For Okta this is okta (required).

• idpIssuerURL - The Okta authorization-server Issuer URL (required).

• proxy-url - The proxy URL that is set up (optional).

• proxy-username - The username to work with the proxy (optional).

• proxy-password - The password related to the username that works with the proxy (optional).

Step 2: Create the Client ID's Configuration

Use the Client ID of the Okta Native application created in the prerequisites.

CLI

REST — POST _api_v2_cluster_idpClientConfs

Fields:

• name - The IdP client configuration name of your choice (required).

• idp-configuration-name - The name of the related idp-configuration entity (required).

• client-id - The Client ID of the Okta application (required).

• authz-mode - The authorization mode the client is configured to work with. For Okta the supported modes are:

  • user - user authentication via the device-code grant flow. The identifier used for access roles is the user’s group(s) information.

  • converge - a fallback for any client application ID that is not explicitly configured. Like user mode, the identifier used for access roles is the user’s group(s) information.

  • Note: app (application) mode is not supported with Okta.

• claim-name - The name of the claim in the token to read the group information from. For Okta this is groups.

Step 3: Create Okta Group Mapping to the Lightbits Role/Scope

Map the Okta groups to the required Lightbits cluster roles and scopes. Repeat this step for each Okta group that should be mapped to a Lightbits scope and role.

CLI

REST — POST _api_v2_cluster_authMaps

Fields:

• name - The authorization map entry name of your choice (required).

• idp-configuration-name - The name of the related idp-configuration entity (required).

• identifier - The Okta group name to be mapped to a Lightbits role and scope. It must match the group name exactly as Okta emits it in the groups claim.

• scope - The scope of the group in the Lightbits cluster (required).

• role - The role of the group in the Lightbits cluster (required).

An Okta group with no matching auth-map entry is silently ignored (not an error), so Okta’s built-in groups (e.g. Everyone) do not interfere with login. Lightbits roles are the standard RBAC set (e.g.; cluster-admin, volume-admin, viewer). See lbcli list roles (2.1 and above) for additional information.

Step 4: Enable the Feature

By default, the federated-authentication functionality is disabled. Run the following command to enable it:

CLI

REST

To disable this functionality, the following command should be run:

CLI

REST

Configuring the Authentication for User Mode (lbcli)

This section applies to a client machine from which a user will run lbcli commands. It requires two additional steps:

• Creating a configuration file on the client machine.

• Logging in.

Creating a Configuration File

Any machine that runs the Lightbits lbcli utility can be configured to interact with the Lightbits cluster using Okta authentication. This machine must have network connectivity to the Okta authorization server, and the following steps should be followed to prepare a local configuration file.

Manually create a file under <USER_HOME_DIR>/.lightbits/.

File name: idp-config.yaml

File permissions: -rw-rw-r-- (0664)

File contents:

1. client_id - The Client ID of the Okta Native application.

2. issuer - The Okta authorization-server Issuer URI, exactly as shown in Okta. This must be an authorization-server URL - e.g.; https://<org>.okta.com/oauth2/<auth-server> (the default server is .../oauth2/default), or your Okta custom-domain equivalent - not the bare org URL.

3. idp_type - The IdP type. For Okta, this is okta.

4. scope - A scope string added to the authorization request. Okta typically requires openid.

idp-config.yaml file example:

For the Okta device-authorization flow, lbcli login polls the Okta token endpoint using the fully-qualified OAuth 2.0 device-code grant type urn:ietf:params:oauth:grant-type:device_code (RFC 8628). This is handled automatically based on idp_type.

At this point, you should be able to run “lbcli login” to authenticate yourself with your credentials and interact with the Lightbits cluster.

Authenticating Using the Authentication Feature on a Client Machine (lbcli)

The login command triggers a handshake with the Okta authorization server that ends with storing local session/authentication information per user, allowing them to access the Lightbits cluster.

To log in, issue the lbcli login command.

• You will receive a prompt with an Okta URL to log into, along with the relevant device/user code (provided by Okta).

• You will then need to either click or copy the provided Okta URL into a browser, and log in using your Okta credentials.

• The lbcli utility will wait for the authentication to take place, and upon successful authentication, fetch the required authorization token and save it locally under the <USER_HOME_DIR>/.lightbits/ directory in a dedicated file called idp-session.yaml. This file is created with limited permissions: -rw------- (0600).

Once logged in, any command executed using the lbcli tool will be executed with the token found in the idp-session.yaml file. This file takes precedence over any other JWTs set in the environment.

The authorization token has an expiration time set by the Okta admin (the default Okta access-token lifetime is one hour). Once the token has expired, you will need to go through the login procedure described above again; the cluster surfaces a token expired error at expiry.

To end the session and clear data, you can optionally log out by issuing the lbcli logout command.

Issuing this command will delete the idp-session.yaml file, which holds the authorization token saved during the login flow described above. After running this command, you will be required to log in again to issue lbcli commands.

lbcli logout is local only. It is not a Single Logout (SLO) operation, and will not invalidate the session within Okta.