Authenticate Accounts via OpenID Connect

Note

OpenID Connect Authentication is a Flower Enterprise feature. See Flower Enterprise for details.

In this guide, you’ll learn how to configure SuperLink with account authentication and how to log in using the flwr CLI. Once logged in, Flower accounts can run CLI commands that interact with the SuperLink.

Important

Account authentication does not replace resource-level access checks. Run ownership, federation membership and roles, and entitlements continue to constrain what an authenticated account can access.

Prerequisites

To enable account authentication, the SuperLink must be deployed with an OpenID Connect (OIDC) provider. The OIDC provider verifies account identity and supplies the account information used by SuperLink’s ownership, federation, and entitlement checks.

Enable Account Authentication on the SuperLink

Set the following environment variables on the SuperLink process:

FLWR_OIDC_ENABLED=1
FLWR_OIDC_ISSUER=https://<domain>/realms/<realm>
FLWR_OIDC_CLIENT_ID=<client_id>
FLWR_OIDC_CLIENT_SECRET=<client_secret>
FLWR_OIDC_VERIFY_TLS=1

FLWR_OIDC_ENABLED defaults to 0. FLWR_OIDC_VERIFY_TLS defaults to 1. As with other Flower binary environment variables, use 1 for true and 0 for false. Control authentication remains NoOp unless FLWR_OIDC_ENABLED=1, even when credentials are present. FLWR_OIDC_VERIFY_TLS affects only requests to the OIDC provider.

Start the SuperLink with these variables in its environment:

$ FLWR_OIDC_ENABLED=1 \
    FLWR_OIDC_ISSUER=https://<domain>/realms/<realm> \
    FLWR_OIDC_CLIENT_ID=<client_id> \
    FLWR_OIDC_CLIENT_SECRET=<client_secret> \
    flower-superlink <other flags>

Login to the SuperLink

Once a SuperLink with account authentication is up and running, an account can interface with it after installing the flwr PyPI package via the Flower CLI. Configure the SuperLink connection in your Flower Configuration file (typically located at $HOME/.flwr/config.toml):

config.toml

[superlink]
default = "my-prod-superlink"  # Set the default connection configuration

[superlink.my-prod-superlink]
address = "<SUPERLINK-ADDRESS>:<CONTROL-API-PORT>"   # Address of the SuperLink Control API
root-certificate = "<PATH/TO/ca.crt>" # TLS certificate set for the SuperLink. Required for self-signed certificates.

Note

• Account authentication is only supported with TLS connections.

• Setting the default connection is optional. If you don’t set your SuperLink as default, you can specify the connection name explicitly in each command, for example: flwr login my-prod-superlink.

Learn more about the Flower Configuration file in the Flower Configuration reference.

You need to login first before other CLI commands can be executed. Upon executing flwr login, a URL will be returned by the authentication plugin in the SuperLink. Click on it and authenticate directly against the OIDC provider.

$ flwr login
A browser window has been opened for you to log into your Flower account.
If it did not open automatically, use this URL:
https://account.flower.blue/realms/flower/device?user_code=...
# [... follows URL and logs in ... in the meantime the CLI will wait ...]
✅ Login successful.

Once the login is successful, the credentials returned by the OIDC provider via the SuperLink will be stored locally. The tokens will be sent transparently with each subsequent flwr CLI request to the SuperLink, and it will relay them to the OIDC provider to perform the authentication checks.

Run authenticated flwr CLI commands

With the above steps completed, you can now run flwr CLI commands against a SuperLink setup with account authentication. For example, you can run the flwr run command to start a Flower app:

$ flwr run
🎊 Successfully started run 1859953118041441032

SuperLink uses the authenticated account identity to enforce access to specific runs and federations through ownership, federation membership and roles, and entitlement checks.