Authentication
Methods

See Configuration: Authentication Methods for details on how to configure the various authentication methods.

Static Token

The token authentication method supports statically creating authentication tokens.

Once enabled, the /auth/v1/method/token API prefix is mounted to Flipt’s API. This section of the API supports the creation of static tokens.

Token Management

Tokens can be created and deleted via either the UI or API.

API

The following curl command creates a static token with no expiration. Given authentication is set to required then a prior client token will be required to perform this action.

curl -X POST localhost:8080/auth/v1/method/token \
    -H 'Authorization: Bearer gt6P_zIqTnCngfHDCpWb48ob5EBt3PqunUhpofNCNnc=' \
    -H 'Content-Type: application/json' \
    --data '{"name":"access_all_areas","description":"keys to the castle"}'

UI

As of version 1.19.0, the UI also supports the creation and deletion of tokens. To access this functionality, navigate to Settings from the main menu and see the ‘Static Tokens’ section.

Create Token UI

Bootstrapping

On first startup, Flipt will automatically create a random static token with the name initial_bootstrap_token if one does not already exist and if token authentication is enabled.

Bootstrap Token

This token is intended to be used to create additional tokens to then be used for subsequent API requests. By default it has no expiration date, therefore it is recommended that this token be deleted once the initial bootstrapping is complete.

This token is output to the Flipt logs on startup and can be found by searching for client_token in the logs:

INFO	access token created	{"server": "grpc", "client_token": "jWLUy8ChnVDs-Llgyj7cMIzB0PfplwbBy-B27a0p23I="}

This initial bootstrap process can also be configured to use a known token by setting the bootstrap.token value in the configuration file. This is useful if you want to prevent having to search the logs after startup or if Flipt is deployed in an automated fashion, for example if you are using a configuration management tool.

The bootstrap token can also be configured to have an expiration date by setting the bootstrap.expiration value in the configuration file. This is useful if you want to ensure that the bootstrap token is only valid for a short period of time before automatically expiring.

See the Configuration: Method Token documentation for more details.

OpenID Connect

OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

Flipts own UI is designed to support this authentication method natively. Meaning, once enabled, the UI will support login and present each provider as a login button.

The rest of this information is mostly academic. It is mainly useful if you want to build your own browser application using cookie authentication or understand Flipt’s OIDC flow at a lower level.

Head over to OIDC Configuration documentation to learn how to configure your provider(s).

The OIDC authentication method is primarily designed to support browser-based authentication. However, it can be manually invoked if such a use case presents itself.

Once enabled, the /auth/v1/method/oidc API prefix is mounted to Flipt’s API. This section of the API supports a generic OAuth 2.0 with OIDC flow.

Flipt’s configuration can be defined with multiple simultaneous OIDC providers. An operator of Flipt chooses a name for each provider and then configures the relevant secrets necessary to authenticate with an OIDC client.

There are many OIDC providers out there. For example, we have tested Flipt with:

  • Google
  • Auth0
  • GitLab
  • Dex
  • Okta

Each provider has their own way of establishing clients and acquiring the relevant credentials. You can find further documentation on leveraging providers like these in our OIDC Configuration documentation.

For illustration purposes, let us say we have configured a single provider with Dex and named it dex (lowercase) in our provider configuration.

This will lead to the following endpoints being available on Flipt:

  • GET /auth/v1/method/oidc/dex/authorize
  • GET /auth/v1/method/oidc/dex/callback

These two endpoints are necessary to support the different legs of the OAuth/OIDC flow. The first can be requested to obtain an authorization URL directed at the configured instance of Dex. The latter is the destination that Dex will redirect the client back to. When using HTTP, this callback endpoint will establish the flipt_client_token and return it via the Set-Cookie response header.

Kubernetes

This method is designed for automatically authenticating applications with Flipt.

We are actively designing and developing client-side implementations to leverage this method seamlessly. However, for now, the API must be managed manually by your implementation.

The kubernetes authentication method supports the ability to exchange Kubernetes service account tokens with Flipt for client tokens. This allows services deployed into the same Kubernetes cluster as Flipt to automatically gain authenticated access to the Flipt API without additional management of static client tokens.

Kubernetes Authentication Flow

When enabled (see our Configuration: Method Kubernetes documentation) a service deployed within Kubernetes can read their service account token from local disk and invoke the verify service account operation on the API. Given the service account is deemed valid for the surrounding cluster this operation will return a valid Flipt client token with a matching expiration as the service account. If your Kubernetes environment has short-lived service account tokens, care will be needed to periodically request a new client token using a newly issued service account token.

Kubernetes refreshes service account tokens locally, all that is required is to read the token from the disk again.

The client token produced can be used in subsequent API requests with the rest of the Flipt API to gain authenticated access.

Via the API

The following can be issued from inside a pod with a valid service account token in the default location for Kubernetes. It assumes that Flipt is reachable and deployed in the same cluster with a service name of flipt.

# assumes both curl and jq are installed
curl -s -X POST http://flipt:8080/auth/v1/method/kubernetes/serviceaccount \
  --data "{\"service_account_token\":\"$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)\"}" | \
  jq .
{
  "clientToken": "pKkaEik40Nu4lJ7O37l92MNyyD38U8UlaagSmAfJoS0=",
  "authentication": {
    "id": "f191babc-57b8-4856-89b1-f324941403d7",
    "method": "METHOD_KUBERNETES",
    "expiresAt": "2024-02-20T13:39:14Z",
    "createdAt": "2023-02-20T14:11:28.962841Z",
    "updatedAt": "2023-02-20T14:11:28.962841Z",
    "metadata": {
      "io.flipt.auth.k8s.namespace": "default",
      "io.flipt.auth.k8s.pod.name": "someservice-586bfb5b6b-fmh8g",
      "io.flipt.auth.k8s.pod.uid": "b5217947-aeac-4b35-afd3-23f50d63eae9",
      "io.flipt.auth.k8s.serviceaccount.name": "default",
      "io.flipt.auth.k8s.serviceaccount.uid": "8aeb28ad-66f0-4884-bafc-e606e5eda149"
    }
  }
}

The client token found in the body of the response can be used in the authentication bearer header, as outlined in Using Client Tokens. The expiration can be used to schedule when to next request a new client token.