From 269b7969aed087121e69d0524df5590e96290d84 Mon Sep 17 00:00:00 2001 From: Mark Phelps <209477+markphelps@users.noreply.github.com> Date: Mon, 11 Dec 2023 10:45:50 -0500 Subject: [PATCH] feat: add github allowed orgs docs (#157) * feat: add github allowed orgs docs * chore: slight rewording --- .vale/styles/Flipt/spelling-exceptions.txt | 1 + authentication/methods.mdx | 11 +++----- concepts.mdx | 12 --------- configuration/authentication.mdx | 31 +++++++++++++++++++--- configuration/overview.mdx | 19 ++++++------- 5 files changed, 42 insertions(+), 32 deletions(-) diff --git a/.vale/styles/Flipt/spelling-exceptions.txt b/.vale/styles/Flipt/spelling-exceptions.txt index fb27c7a..7932d4e 100644 --- a/.vale/styles/Flipt/spelling-exceptions.txt +++ b/.vale/styles/Flipt/spelling-exceptions.txt @@ -33,6 +33,7 @@ memcached Minio mintlify namespace +namespaced namespaces nginx ngrok diff --git a/authentication/methods.mdx b/authentication/methods.mdx index b508801..7eec406 100644 --- a/authentication/methods.mdx +++ b/authentication/methods.mdx @@ -89,7 +89,7 @@ Meaning, once enabled, the UI will support login and present each provider as a The rest of this information is mostly academic. It's 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](/configuration/authentication#method-oidc) documentation to learn how to configure your provider(s). +See the [OIDC Configuration](/configuration/authentication#oidc) documentation to learn how to configure your provider(s). @@ -113,7 +113,7 @@ Numerous OIDC providers are available. For example, we've tested Flipt with: - Keycloak 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](/configuration/authentication#method-oidc) documentation. +You can find further documentation on leveraging providers like these in our [OIDC Configuration](/configuration/authentication#oidc) documentation. For illustration purposes, let us say we've configured a single provider with `Dex` and named it `dex` (lowercase) in our provider configuration. @@ -147,10 +147,7 @@ This will lead to the following endpoints being available on Flipt: - `GET /auth/v1/method/github/authorize` - `GET /auth/v1/method/github/callback` -These two endpoints are necessary to support the different legs of the OAuth flow. -The first can be requested to obtain an authorization URL directed at GitHub. -The latter is the destination that GitHub will redirect the client back to. -When using HTTP, this callback endpoint will establish a cookie named `flipt_client_token` and return it via the `Set-Cookie` response header. +These two endpoints are necessary to support the different legs of the OAuth flow. The first can be requested to obtain an authorization URL directed at GitHub. The latter is the destination that GitHub will redirect the client back to. When using HTTP, this callback endpoint will establish a cookie named `flipt_client_token` and return it via the `Set-Cookie` response header. ## Kubernetes @@ -167,7 +164,7 @@ This allows services deployed into the same Kubernetes cluster as Flipt to autom ![Kubernetes Authentication Flow](/images/authentication/kubernetes.svg) -When enabled (see our [Configuration: Method Kubernetes](/configuration/authentication#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. +When enabled (see our [Configuration: Method Kubernetes](/configuration/authentication#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. diff --git a/concepts.mdx b/concepts.mdx index 50f1f28..6de6bdd 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -186,18 +186,6 @@ about your current user to determine if they're a `new-user`, and which color ![Evaluation Example](/images/concepts/evaluation.png) - - A new set of evaluation endpoints exist as of v1.24.0 of Flipt: - - `/evaluate/v1/boolean` - - `/evaluate/v1/variant` - - `/evaluate/v1/batch` - - See the API documentation for more information: [API Reference](/reference/overview). - - These endpoints should be used going forward. The `/api/v1/evaluate` and `/api/v1/batch-evaluate` endpoints are considered deprecated. - - - ### Entities Evaluation works by uniquely identifying each _thing_ that you want to compare diff --git a/configuration/authentication.mdx b/configuration/authentication.mdx index 7bcd4bc..7fe09a7 100644 --- a/configuration/authentication.mdx +++ b/configuration/authentication.mdx @@ -91,7 +91,7 @@ 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 +### Static Token The `token` method provides the ability to create client tokens statically, with optional expiry constraints. @@ -108,7 +108,7 @@ Once enabled, static tokens can be created via the [CreateToken](/reference/auth Further explanation for using this method can be found in the [Authentication: Static Token](/authentication/methods#static-token) documentation. -### Method: OIDC +### OIDC The `OIDC` method is a `session compatible` authentication method. @@ -269,7 +269,7 @@ Other providers have similar mechanisms for attenuating who can leverage this au -### Method: GitHub +### GitHub The `GitHub` method is a `session compatible` authentication method. @@ -297,7 +297,30 @@ authentication: !["GitHub Login"](../images/guides/login-with-github/login-with-github.png) -### Method: Kubernetes +#### 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: + +```yaml config.yaml +authentication: + 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. + + +### Kubernetes The `kubernetes` method provides the ability to exchange Kubernetes service account tokens for client tokens. diff --git a/configuration/overview.mdx b/configuration/overview.mdx index 0b66112..07eb9ae 100644 --- a/configuration/overview.mdx +++ b/configuration/overview.mdx @@ -162,15 +162,16 @@ export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001" #### Authentication Methods: GitHub -| Property | Description | Default | Since | -| -------------------------------------------------- | -------------------------------------------------------------- | ------- | ------- | -| authentication.methods.github.enabled | Enable GitHub authentication | false | v1.26.0 | -| authentication.methods.github.cleanup.interval | Interval between deletion of expired tokens | 1h | v1.26.0 | -| authentication.methods.github.cleanup.grace_period | How long an expired token can exist until considered deletable | 30m | v1.26.0 | -| authentication.methods.github.client_id | GitHub client ID | | v1.26.0 | -| authentication.methods.github.client_secret | GitHub client secret | | v1.26.0 | -| authentication.methods.github.redirect_address | Public URL on which this Flipt instance is reachable | | v1.26.0 | -| authentication.methods.github.scopes | Scopes to request from GitHub | | v1.26.0 | +| Property | Description | Default | Since | +| --------------------------------------------------- | -------------------------------------------------------------- | ------- | ------- | +| authentication.methods.github.enabled | Enable GitHub authentication | false | v1.26.0 | +| authentication.methods.github.cleanup.interval | Interval between deletion of expired tokens | 1h | v1.26.0 | +| authentication.methods.github.cleanup.grace_period | How long an expired token can exist until considered deletable | 30m | v1.26.0 | +| authentication.methods.github.client_id | GitHub client ID | | v1.26.0 | +| authentication.methods.github.client_secret | GitHub client secret | | v1.26.0 | +| authentication.methods.github.redirect_address | Public URL on which this Flipt instance is reachable | | v1.26.0 | +| authentication.methods.github.scopes | Scopes to request from GitHub | | v1.26.0 | +| authentication.methods.github.allowed_organizations | List of GitHub organizations allowed to authenticate | | v1.33.0 | #### Authentication Methods: Kubernetes