Authentication

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

config.yaml
authentication:
  required: true

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

Once authentication has been set to required: true all API routes will require a client token to be present.

The UI will require a session-compatible authentication method (e.g. OIDC) to be enabled.

Exclusions

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

For example:

/evaluate/v1 is the application facing flag state evaluation API

Several 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 to manage feature-flag configuration and state.

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

config.yaml
authentication:
  required: true
  exclude:
    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:

config.yaml
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.

config.yaml
authentication:
  required: true
  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.

Using openssl to generate a 64-byte CSRF key

openssl rand -base64 64

Session Storage

Session storage allows you to configure where the session data is stored. All session enabled authentication methods will use the same configured session storage backend.

Currently, Flipt v2 supports the following session storage backends:

memory
redis

Memory

The memory backend is the default and will store session data in memory. This means that the session data will be lost when the Flipt server restarts.

config.yaml
authentication:
  required: true
  session:
    storage:
      type: memory

Redis

The redis backend will store session data in a Redis instance. This means that the session data will be persisted across Flipt server restarts and can be shared across multiple Flipt servers.

config.yaml
authentication:
  required: true
  session:
    storage:
      type: redis
      redis:
        host: localhost
        port: 6379
        db: 0
        password: password

Session Cleanup

Session cleanup is a feature that allows you to configure the periodic deletion of expired authentications created with the associated method.

config.yaml
authentication:
  required: true
  session:
    cleanup:
      grace_period: 24h

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.

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.

Static Token

The token method is NOT a session compatible authentication method.

The token method provides the ability to create client tokens statically, defined in the configuration file.

config.yaml
authentication:
  required: true
  methods:
    token:
      enabled: true
      storage:
        tokens:
          "some_token_id":
            credential: "some_token_credential"
            metadata:
              some_key: "some_value"

OIDC

The OIDC method is a session compatible authentication method.

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.

config.yaml
authentication:
  required: true
  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 provider will result in a login option being presented in the UI, along with a configured endpoint to support the provider flow.

Flipt v2 has been tested with each of the following providers:

Though the intention is that it should work with all 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 must request the email scope from your OIDC provider in order for this feature to work.

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:

config.yaml
authentication:
  required: true
  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

The redirect URL for this provider would be https://flipt.myorg.com/auth/v1/method/oidc/google/callback.

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.

Google’s consent screen can be configured to only accept accounts that are within your Google Workspace organization.

Other providers have similar mechanisms for attenuating who can leverage this authentication flow.

GitHub

The GitHub method is a session compatible authentication method.

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.

config.yaml
authentication:
  required: true
  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

Allowed Organizations

The GitHub authentication method supports the ability to restrict access to a set of GitHub organizations. This is important if you want to limit access to Flipt to only members of a specific organization as opposed to all GitHub users.

To enable this feature, set the github.allowed_organizations configuration value to a list of GitHub organizations. For example:

config.yaml
authentication:
  required: true
  methods:
    github:
      enabled: true
      scopes:
        - read:org
      allowed_organizations:
        - my-org
        - my-other-org

The read:org scope is required to retrieve the list of organizations that the user is a member of.

Allowed Teams

The GitHub authentication method also supports the ability to restrict access to a set of GitHub teams. This is important if you want to limit access to Flipt to only members of a specific team within an organization as opposed to all members of the organization.

To enable this feature, set the github.allowed_teams configuration value to a list of GitHub teams within existing allowed organizations. For example:

config.yaml
authentication:
  required: true
  methods:
    github:
      enabled: true
      scopes:
        - read:org
      allowed_organizations:
        - my-org
        - my-other-org
      allowed_teams:
        my-org:
          - my-team
        my-other-org:
          - my-other-team

The organizations to check for team membership must be included in the allowed_organizations list.

Kubernetes

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

config.yaml
authentication:
  required: true
  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.

Troubleshooting

verifying service account: failed to verify signature: fetching keys oidc

In some managed Kubernetes cluster environments, the default cluster OIDC provider is replaced with the platform’s managed alternative. For example, EKS clusters leverage this so that they can issue service account tokens which can assume the capabilities of AWS IAM roles.

In this situation, the default OIDC discovery URL isn’t appropriate for fetching key material from. Instead, you should locate your clusters OIDC URL and use that instead.

Your cluster’s OIDC URL will vary between Kubernetes providers. For example, here is some documentation which should help for EKS: EKS troubleshoot OIDC and IRSA.

It’s also important to note that custom OIDC providers likely will use HTTPS which has been signed with certificates not authorized by the cluster TLS certificate authority. In this situation, you can override the kubernetes auth providers ca_path field with relevant key material. The flipt distributed Docker image has valid and trusted certificates in /etc/ssl/certs/ca-certificates.crt, which can be appropriate if your OIDC provider has certificates granted by a valid public certificate authority.

example-config-for-eks.yaml
authentication:
  required: true
  methods:
    kubernetes:
      enabled: true
      discovery_url: https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E # note: yours will be different
      ca_path: /etc/ssl/certs/ca-certificates.crt # this can be enough if your OIDC provider TLS certificates have been signed by a public certificate authority

See this issue for more context.

JSON Web Token

The jwt method provides the ability to authenticate with Flipt using an externally issued JSON Web Token. This method is useful for integrating with other authentication systems that can issue JWTs (e.g. Auth0) or by generating your own signed JWTs on the fly.

Flipt supports asymmetrically signed JWTs using the following algorithms:

RS256
RS512
ES256
ES512
EdDSA

This means that the JWT must be signed using a private key leveraging one of these algorithms and Flipt must be configured with the corresponding public key.

Flipt supports key verification using the following methods:

JWKS URL (JSON Web Key Set URL)
PEM (Privacy Enhanced Mail) encoded public key

These methods are mutually exclusive, meaning that only one of them can be configured at a time.

JWKS URL

The jwks_url configuration value is a URL that points to a JWKS (JSON Web Key Set) endpoint. This endpoint must return a JSON object that contains a list of public keys that can be used to verify the JWT signature.

config.yaml
authentication:
  required: true
  methods:
    jwt:
      enabled: true
      jwks_url: https://auth0.com/.well-known/jwks.json

PEM Encoded Public Key

The public_key_file configuration value is the path to a PEM encoded public key that can be used to verify the JWT signature.

config.yaml
authentication:
  required: true
  methods:
    jwt:
      enabled: true
      public_key_file: /path/to/public_key.pem

Claim Validation

Flipt supports validating the following claims:

iss (issuer)
aud (audience)
sub (subject)
exp (expiration time)
nbf (not before)
iat (issued at)

The exp, nbf, and iat claims are validated by default.

To enable claim validation, configure the values in the validate_claims configuration option to the expected values.

config.yaml
authentication:
  required: true
  methods:
    jwt:
      enabled: true
      validate_claims:
        issuer: https://auth0.com/
        subject: user@domain.com
        audiences: https://flipt.io/, https://flipt.com/ # at least one audience must match

Overview

Configuration

Guides

Authentication

Exclusions

Session

Using openssl to generate a 64-byte CSRF key

Session Storage

Memory

Redis

Session Cleanup

Methods

Static Token

OIDC

Callback URL

Email Matches

PKCE

Example: OIDC With Google

GitHub

Allowed Organizations

Allowed Teams

Kubernetes

Troubleshooting

JSON Web Token

JWKS URL

PEM Encoded Public Key

Claim Validation

Overview

Configuration

Guides

​Exclusions

​Session

Using openssl to generate a 64-byte CSRF key

​Session Storage

​Memory

​Redis

​Session Cleanup

​Methods

​Static Token

​OIDC

​Callback URL

​Email Matches

​PKCE

​Example: OIDC With Google

​GitHub

​Allowed Organizations

​Allowed Teams

​Kubernetes

​Troubleshooting

​JSON Web Token

​JWKS URL

​PEM Encoded Public Key

​Claim Validation

Exclusions

Session

Session Storage

Memory

Redis

Session Cleanup

Methods

Static Token

OIDC

Callback URL

Email Matches

PKCE

Example: OIDC With Google

GitHub

Allowed Organizations

Allowed Teams

Kubernetes

Troubleshooting

JSON Web Token

JWKS URL

PEM Encoded Public Key

Claim Validation