Authenticate Accounts via OpenID Connect

참고

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-level authentication and authorization, and how to log in using the flwr CLI. Once logged in, any Flower accounts that are authorized on the SuperLink can run Flower CLI commands that interact with the SuperLink.

중요

With account authentication and authorization enabled, only accounts that have submitted the flwr run command can view and interact with their runs. This means that your runs are private by default, ensuring that only authorized accounts can access them.

전제 조건

To enable account authentication and authorization, the SuperLink must be deployed with an OpenID Connect (OIDC) provider and an OpenFGA server. The OIDC provider is used for account authentication, while OpenFGA is used for fine-grained access control. This means an authenticated account can only run flwr CLI commands on the SuperLink if they have been granted the necessary permissions by the SuperLink administrator. When enabled, both account authentication and authorization must be configured on the SuperLink.

Enable Account Authentication and Authorization on the SuperLink

Create a YAML configuration file with the following content:

authentication:
  authn_type: oidc
  authn_url:          # OIDC provider's authorization_endpoint
  token_url:          # OIDC provider's token_endpoint
  validate_url:       # OIDC provider's account-authinfo_endpoint
  oidc_client_id:     # OIDC provider Client ID
  oidc_client_secret: # The corresponding Client Secret

authorization:
  authz_type: openfga
  authz_url:          # The base OpenFGA API URL
  store_id:           # The store ID containing the model store
  model_id:           # The model ID containing the latest authorization model for the SuperLink
  relation:           # The authorized relation between the account and the resource, e.g. `has_access`
  object:             # The object and identifier at which an account has an authorized relation.
                      # The expected format is `object_type:object_identifier`, e.g.:
                      #   service:researchgrid
                      #   │       └─ Identifier of the object
                      #   └─ Object type

Save this file as account-auth-config.yaml. Then pass it to the SuperLink via the --account-auth-config flag when deploying the SuperLink:

➜ flower-superlink \
    --account-auth-config=account-auth-config.yaml
    <other flags>

참고

To authorize an account, the SuperLink administrator must add the account’s OIDC sub claim to the OpenFGA store with the appropriate relation.

경고

Starting with Flower v1.23.0, the following options/keys have been renamed:

• auth_type → authn_type (in YAML configuration)

• auth_url → authn_url (in YAML configuration)

• --user-auth-config → --account-auth-config (in SuperLink CLI)

Login to the SuperLink

Once a SuperLink with account authentication and authorization is up and running, an account can interface with it after installing the flwr PyPI package via the Flower CLI. Then, ensure that the enable-account-auth field is set to true in the federation section in the pyproject.toml of the Flower app you want to run:

[tool.flwr.federations]
default = "my-federation"

[tool.flwr.federations.my-federation]
address = "<SUPERLINK-ADDRESS>:9093"   # Address of the SuperLink Control API
root-certificates = "<PATH/TO/ca.crt>" # TLS certificate set for the SuperLink. Required for self-signed certificates.
enable-account-auth = true                # Enables the account auth mechanism on the `flwr` CLI side

참고

Account authentication and authorization is only supported with TLS connections.

Now, 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 [APP] [FEDERATION]
Loading project configuration...
Success
Creating a new `.gitignore` with `.credentials` entry...
Please login with your account credentials here: https://account.flower.ai/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 saved to the app’s directory under .flwr/.credentials/<federation-name>.json. The tokens stored in this file will be sent transparently with each subsequent flwr CLI request to the SuperLink, and it will relay them to OIDC provider to perform the authentication checks.

Run authorized flwr CLI commands

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

➜ flwr run
Loading project configuration...
Success
🎊 Successfully built flwrlabs.myawesomeapp.1-0-0.014c8eb3.fab
🎊 Successfully started run 1859953118041441032

If the account does not have the necessary permissions to run the command, an error will be returned:

➜ flwr run
Loading project configuration...
Success
❌ Permission denied.
Account not authorized