Authentication

Flipt supports the ability to secure its core API routes by setting the required field to true on the authentication configuration object.

authentication:
  required: true

When authentication is set to required, the API will ensure valid credentials are present on all API requests.

See the Authentication: Overview documentation for more details on Flipt’s API authentication handling.

​

Exclusions

Exclusions allow you to disable authentication for sections of the API. The Flipt API is made of up of top-level API sections, each with its own unique prefix:

• /api/v1 is the core feature flag state management section
• /meta describes the configuration of the running Flipt instance
• /evaluate/v1 is the application facing flag state evaluation API

Each of these API sections can be optionally omitted from requiring authentication. A common use case is to allow the evaluation API to be publicly accessible while still requiring authenticated users for managing feature-flag configuration and state.

By default, when authentication is configured as required: true, the effective configuration for the exclusions looks like this:

authentication:
  required: true
  exclude:
    management: false
    metadata: false
    evaluation: false

This means every part of the Flipt API is required for authentication. However, taking the example from before, we could skip authentication for the evaluation section of the Flipt API like so:

authentication:
  required: true
  exclude:
    evaluation: true

​

Session

This section contains common properties for establishing browser sessions via a “session compatible” authentication method. Session-compatible methods enable support for login in the UI. The methods below state whether or not they’re session compatible (e.g. OIDC is session compatible).

In order to establish a browser session over HTTP (via a Cookie header) some configuration is required.

authentication:
  session:
    domain: "flipt.yourorg.com"
    secure: true
    csrf:
      key: "some_secret_string"

When a “session compatible” authentication method is enabled the domain property is required. It should be configured with the public domain your Flipt instance is hosted on. The other properties aren’t required to be explicitly configured.

To best secure your instance of Flipt, we advise that you run Flipt with secure: true. This will require you to expose Flipt over HTTPS. Additionally, we advise that you configure a csrf.key with a 32 or 64-byte random string of data.

openssl rand -base64 64

​

Methods

Each key within the methods section is a particular authentication method. These methods are disabled (enabled: false) by default. Enabling and configuring a method allows for different ways to establish client token credentials within Flipt.

​

Method: Static Token

The token method provides the ability to create client tokens statically, with optional expiry constraints.

authentication:
  methods:
    token:
      enabled: true
      bootstrap:
        expiration: 24h

Once enabled, static tokens can be created via the CreateToken operation in the API.

Further explanation for using this method can be found in the Authentication: Static Token documentation.

​

Method: OIDC

The oidc method provides the ability to establish client tokens via OAuth 2.0 with OIDC flow. Once enabled and configured, the UI will automatically leverage it and present any configured providers as login options.

authentication:
  methods:
    oidc:
      enabled: true
      email_matches:
        - ^.*@flipt.io$
      providers:
        some_provider: # insert your provider name
          issuer_url: "https://some.oidc.issuer.com"
          client_id: "some_client_identifier"
          client_secret: "some_client_secret_credential"
          redirect_address: "https://your.flipt.instance.url.com"
          scopes:
            - email
            - profile

Multiple providers can be configured simultaneously. Each will result in a Login option being presented in the UI, along with a separate endpoint being added in the API to support each provider flow.

Flipt has been tested with each of the following providers:

• Google
• Auth0
• GitLab
• Dex
• Okta

Though the intention is that it should work with other OIDC providers, these are just the handful the Flipt team has validated.

Following any of the links above should take you to the relevant documentation for each of these providers’ OIDC client setups. You can use the credentials and client configuration obtained using those steps as configuration for your Flipt instance.

​

Callback URL

When configuring your OIDC provider, you will need to provide a callback URL for the provider to redirect back to Flipt after a successful login.

The callback URL will be in the form of https://your.flipt.instance.url.com/auth/v1/method/oidc/{provider}/callback.

You can find the callback URL for each provider that you configure in your Flipt instance by querying the API.

curl --request GET \
  --url https://your.flipt.instance.url.com/auth/v1/method \
  --header 'Accept: application/json'

{
  "methods": [
    {
      "method": "METHOD_TOKEN",
      "enabled": true,
      "sessionCompatible": false,
      "metadata": null
    },
    {
      "method": "METHOD_OIDC",
      "enabled": true,
      "sessionCompatible": true,
      "metadata": {
        "providers": {
          "google": {
            "authorize_url": "/auth/v1/method/oidc/google/authorize",
            "callback_url": "/auth/v1/method/oidc/google/callback"
          }
        }
      }
    }
  ]
}

​

Email Matches

Flipt operators may wish to lock down access to the Flipt API and UI to a specific group of users within their organization behind OIDC. Since OIDC has the ability to retrieve email addresses, Flipt also provides a configuration option of using email_matches which are regular expressions that can be used to match against the OIDC email.

You can see an example of that above in the sample configuration.

​

PKCE

A good amount of OIDC providers support the PKCE (Proof Key for Code Exchange) flow and the implicit OAuth flow. Flipt allows for a configuration to enable PKCE for all the legs of the OIDC authentication flow.

To enable this, you must set the use_pkce property to true for each provider you would like to leverage PKCE with.

​

Example: OIDC With Google

Given we’re running our instance of Flipt on the public internet at https://flipt.myorg.com.

Using Google as an example and the documentation linked above, we obtained the following credentials for a Google OAuth client:

client_id: "CyJcdvQMadOjSEx7ArArom0ytrbIHWd2Fb3N59oh8NQ="
client_secret: "WGgJmfQqN7cf17dFyZKXDL5S445/qhp+hfDAC0Mnl7oBrxgdAgiMyuwCkPiwfgQy"

We could create a provider definition in our configuration like so:

authentication:
  methods:
    oidc:
      enabled: true
      providers:
        google:
          issuer_url: "https://accounts.google.com"
          client_id: "CyJcdvQMadOjSEx7ArArom0ytrbIHWd2Fb3N59oh8NQ="
          client_secret: "WGgJmfQqN7cf17dFyZKXDL5S445/qhp+hfDAC0Mnl7oBrxgdAgiMyuwCkPiwfgQy"
          redirect_address: "https://flipt.myorg.com"
          scopes:
            - email
            - profile

Additional scopes such as profile aren’t 100% necessary, however, adding them will result in Flipt being able to identify more details about your users such as personalized greeting messages and user profile pictures in the UI.

Once this configuration has been enabled a Login with Google option will be presented in the UI. Clicking this button will navigate the user to a Google consent screen. Once the user has authenticated with Google, they will be redirected to the address defined in the redirect_address section of the provider configuration.

​

Method: GitHub

The github method provides the ability to establish client tokens via OAuth 2.0 with GitHub as the identity provider. Once enabled and configured, the UI will automatically leverage it and present a “Login with GitHub” button.

authentication:
  methods:
    github:
      enabled: true
      client_id: "some_client_identifier"
      client_secret: "some_client_secret_credential"
      redirect_address: "https://your.flipt.instance.url.com"
      scopes:
        - user:email

​

Method: Kubernetes

The kubernetes method provides the ability to exchange Kubernetes service account tokens for client tokens.

authentication:
  methods:
    kubernetes:
      enabled: true
      discovery_url: https://kubernetes.default.svc.cluster.local
      ca_path: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
      service_account_token_path: /var/run/secrets/kubernetes.io/serviceaccount/token

Once enabled, client tokens can be retrieved by sending a Kubernetes pod’s service account token to the VerifyServiceAccount operation in the API.

Further explanation for using this method can be found in the Authentication: Kubernetes documentation.

​

Common Properties: Cleanup

Each authentication method contains a nested cleanup configuration object. This object configures the periodic deletion of expired authentications created with the associated method.

authentication:
  <method>:
    cleanup:
      interval: 10m
      grace_period: 24h

The cleanup object currently contains two keys interval and grace_period. The interval is used to configure how frequently a delete expired tokens action is performed. Whereas, grace_period is used to ensure that expired tokens are preserved for at least this configured duration.

This allows you to keep authentications around for auditing purposes after expiration. Expired tokens are instances where the expires_at timestamp occurs before the current time. The grace period is added onto this timestamp as a predicate when the delete operation is made.

Tokens that have expired (expires_at is before now()) will begin immediately failing authentication when presented as a credential to the API. The grace_period is simply for the cleanup process.

​

Reverse Proxy

You can secure Flipt simply by running it behind a reverse proxy in your own trusted environment. An example of this can be found in authentication examples in the Flipt repository.