This document describes how to configure Flipt’s authentication mechanisms.
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.required
field to true
on the authentication
configuration object.
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.
/api/v1
is the core feature flag state management section/evaluate/v1
is the application facing flag state evaluation APIrequired: true
, the effective configuration for the exclusions looks like this:
Cookie
header) some configuration is required.
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.
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.
token
method provides the ability to create client tokens statically, with optional expiry constraints.
OIDC
method is a session compatible
authentication method.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.
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.
email_matches
which are regular expressions that can be used to match against the OIDC email.
email
scope from your OIDC provider in order for this
feature to work.use_pkce
property to true
for each provider you would like to leverage PKCE with.
https://flipt.myorg.com
.
Using Google as an example and the documentation linked above, we obtained the following credentials for a Google OAuth client:
https://flipt.myorg.com/auth/v1/method/oidc/google/callback
.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.
GitHub
method is a session compatible
authentication method.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.
github.allowed_organizations
configuration value to a list of GitHub organizations. For example:
read:org
scope is required to retrieve the list of organizations that
the user is a member of.github.allowed_teams
configuration value to a list of GitHub teams within existing allowed organizations. For example:
allowed_organizations
list.kubernetes
method provides the ability to exchange Kubernetes service account tokens for client tokens.
VerifyServiceAccount
operation in the API.
Further explanation for using this method can be found in the Authentication: Kubernetes documentation.
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.
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:
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.
public_key_file
configuration value is the path to a PEM encoded public key that can be used to verify the JWT signature.
iss
(issuer)aud
(audience)sub
(subject)exp
(expiration time)nbf
(not before)iat
(issued at)exp
, nbf
, and iat
claims are validated by default.validate_claims
configuration option to the expected values.
cleanup
configuration object.
This object configures the periodic deletion of expired authentications created with the associated method.
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.