Federated Authentication (ADFS)
Federated Authentication (ADFS) in Lightbits clusters allows you to use your existing identity provider (IdP) infrastructure for authentication. This capability eliminates the need to manage local users on the Lightbits system, and provides seamless integration with your IdP.
This functionality enables authorization for both users and applications/scripts. In OAuth 2.0, various grant flows are defined, allowing users or applications to obtain an authorization token (JWT).
Lightbits ADFS offers support for:
- Device Authorization Flow: User mode - for users interacting directly with the Lightbits cluster using the Lightbits CLI utility.
- Client Credentials Flow: App mode - for applications that interact with the Lightbits cluster using Lightbits’ REST API.
High-Level ADFS Workflow
This section details the high-level workflow for using ADFS.
Implementing this feature consists of two main steps:
- Initial configurations on the Lightbits cluster, supported by new dedicated Lightbits APIs:
- Configure information describing the required ADFS server (the IdP).
- Configure information of IdP client configurations.
- Create mapping table entries of ActiveDirectory (AD) groups (for user mode) or client IDs (for application mode) to Lightbits’ scope and role (referred to as AuthMap).
- In user’s mode only:
- Prepare a configuration file for the LBCLI utility, with Information on IdP.
Once the configurations are set, you can use a dedicated Lightbits CLI to log in using ADFS. You can also 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.
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 IdP server.
- 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
CLI
lbcli create idp-configuration --name=<IdP configuration preferred name> --idp-issuer-url=<IdP Issuer URL> --type=<IdP type>[--proxy-url <proxy URL>] [--proxy-username <proxy username>] [--proxy-password <proxy password>]REST
POST /api/v2/cluster/IdpConfigurationBody: "name": <IdP configuration preferred name>, "idpIssuerURL": <IdP Issuer URL>, "type": enum_type, "proxy -url": <Proxy URL>, "proxy-username": <Proxy username>, "proxy-password": <Proxy password><name> - The IdP configuration name of your choice (required).<type> - The IdP type (ADFS) (required).<idp-issuer-url> - The IdP 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 IDs' Configurations
CLI
lbcli create idp-client-configuration --name <IdP client configuration preferred name> --idp-configuration-name <Related configuration name in IdP configuration> --client-id <Client id in IdP server> --authz-mode <user|app|converge> --claim-name <Claim name holding the identifier information>REST
POST /api/v2/cluster/idpClientConfsBody: “name”: <IdP client configuration preferred name>,"idp-configuration-name": <IdP configuration name>, "client-id": <client_id_in_idp_server>, "authz-mode": enum_type, "claim-name": <claim_name_holding_the_identifier_information><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 in the IdP server (required).<authz-mode> - The type of authorization mode the client is configured to work with. Supported modes are:‘user’ - to be used for user’s authentication (device code grant flow). The identifier that will be used for access roles will be the user’s group(s) information.‘app’ - to be used for app2app authentication (client credentials grant flow). The identifier that will be used for access roles will be the application client id.‘converge’ - to be used for any client application id that is not explicitly configured. Similar to user’s mode, the identifier that will be used for access roles will be the user’s group(s) information.<claim-name> - To be used for ‘user’ or ‘converge’ mode, this is the name of the claim in the token to get the groups' information from.Step 3: Create AD Access Groups Mapping to the Lightbits Role/Scope
Map the AD groups or client IDs to the required Lightbits cluster roles and scopes. Repeat this step for each AD group or client ID that should be mapped to a Lightbits scope and role.
CLI
lbcli auth-map-entry --name <Authorization map entry preferred name> --idp-configuration-name <Related configuration name in IdP configuration> --identifier <AD group name|client id> --scope=<Lightbits scope> --role=<Lightbits role>REST
POST: /api/v2/cluster/authMapsBody: “name”: <Authorization map entry preferred name>,"idp-configuration-name": <IdP configuration name>,“identifier”: <Identifier to be mapped for scope and role>,"scope": <Lightbits scope>,"role": <Lightbits role>,<name> - The authorization map entry name of your choice (required).<idp-configuration-name> - The name of the related idp-configuration entity (required).<identifier> - The identifier's value to be mapped for Lightbits’ role and scope. For user or converge modes, these are the required users’ AD groups to be mapped. For app mode, this is the application client ID.<scope> - The scope of the group in the Lightbits cluster (required).<role> - The role of the group in the Lightbits cluster (required)At this point, you will need to enable the feature (see step 4 below). Once the feature is enabled, you will be able to use the REST API to run almost any Lightbits command from any client machine. Using CLI requires additional configuration on a client machine. This is detailed in the next section.
Step 4: Enable the Feature
By default, the ADFS functionality is disabled. Run the following command to enable this functionality:
CLI
lbcli enable federated-authenticationREST
POST: /api/v2/cluster/federatedAuthentication/enableBody: noneTo disable this functionality, the following command should be run:
CLI
lbcli disable federated-authenticationREST
POST: /api/v2/cluster/federatedAuthentication/disableBody: noneOnce enabled, any valid Lightbits-issued JWTs will still remain active and can be used for accessing the Lightbits services. For additional information, refer to Operational Best Practices and Maintenance.
Configuring the Authentication for User Mode (lbcli)
This section is relevant to a client application that is set to run for user’s authorization mode (authz-mode=user). This requires two additional steps:
- Creating a configuration file on the client machine from which the user will run CLI commands.
- Logging in.
Creating a Configuration File
Any machine that runs the Lightbits lbcli utility can be configured to interact with the Lightbits cluster using ADFS authentication. This machine must have network connectivity to the IdP 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:
- client_id - The client ID of the user’s application in ADFS.
- issuer - The IdP issuer URL.
- idp_type - The IdP type (currently “ADFS”).
- scope - An ADFS scope string that could be required by the IdP to be added to authorization requests. This is optional and should be set if required by the IdP for interaction.
idp-config.yaml file example:
client_id: xxx-yyy-123issuer: https://your_idp_url/adfsidp_type: ADFSscope: some_scope_string - optionalAt 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 will trigger a handshake with the IdP server that will end up 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 IdP URL to log into, with the relevant device code (provided by the ADFS server).
- You will then need to either click or copy the provided IdP URL to a browser, and log in using your credentials provided by the AD admin.
- 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 will be 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 IdP admin. Once the token has expired, you will need to go through the login procedure described above again.
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 the lbcli commands.
lbcli logout is local only. It is not a Single Logout (SLO) operation, and will not invalidate the session within the IdP.
Configuring the Authentication on a Client Machine (REST API)
When using the REST API, the provisioning of authorization tokens should be managed by the client application. The client-side application is responsible for handling the lifecycle of these tokens.
Client applications should negotiate reception of the token directly with the IdP server, using a grant method such as Client Credentials (either with a client secret or x509 certificate - see the definition in OAuth 2.0 RFC 6749, section 4.4). It can then be passed to the Lightbits cluster via the REST commands as the bearer token.