From 218771a48cc2b5124c8ecf2ca11d5d56b3f98ebf Mon Sep 17 00:00:00 2001 From: Roman Dmytrenko Date: Wed, 5 Jun 2024 13:29:26 +0300 Subject: [PATCH] fix(guides): clean up login with Github operation guide - remove Ngrok as it isn't required - fix the dashboard image --- .../authentication/login-with-github.mdx | 27 +++++++------------ 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/guides/operation/authentication/login-with-github.mdx b/guides/operation/authentication/login-with-github.mdx index 0e4ea3a..edd6af6 100644 --- a/guides/operation/authentication/login-with-github.mdx +++ b/guides/operation/authentication/login-with-github.mdx @@ -11,7 +11,6 @@ Alongside the support for generic OIDC login, Flipt has launched support for log - [Docker](https://www.docker.com/) - [GitHub](https://github.com/) -- [Ngrok](https://ngrok.com/) ## Brief Explanation of OAuth 2.0 @@ -35,17 +34,11 @@ In comparison to OIDC, OAuth 2.0 doesn't have an identity standard, so retrievin - `Application Name`: Give your application a meaningful name - `Homepage URL`: Usually Flipt will be used internally by organizations, so this value depends on how you plan to expose Flipt. When in doubt you can just use the URL to your organization's home page -- `Authorization callback URL`: This value requires a publicly accessible endpoint on the internet. Thankfully, there are tools such as [ngrok](https://ngrok.com/) that will allow public traffic to an application running locally. Since we will be running Flipt in a Docker container locally, you can fire up `ngrok` and point it to port 8080 on your local machine, with the following command: - -```bash -$ ngrok http 8080 -``` - -Copy the https URL that `ngrok` provides, and append `/auth/v1/method/github/callback` to it. This will be the value you should put for the callback URL. (e.g. `https://36f1-2600-1700-1d64-daa0-444c-3f7e-ceb7-3825.ngrok-free.app/auth/v1/method/github/callback`). +- `Authorization callback URL`: For this value, you'll need your Flipt URL followed by `/auth/v1/method/github/callback`. Since we will be running Flipt in a Docker container locally, we will use `http://localhost:8080/auth/v1/method/github/callback` instead of actual Flipt URL. - We're using `ngrok` here for illustration purposes. In a production setting, - you would use whichever publicly accessible domain name you have configured + We're using `localhost:8080` here for illustration purposes. In a production setting, + you would use whichever accessible domain name you have configured for your Flipt deployment. These values can always be changed later after the creation of the application. @@ -81,14 +74,14 @@ authentication: enabled: true client_id: "< client ID from GitHub >" client_secret: "< client secret from GitHub >" - redirect_address: "< ngrok URL with no path >" + redirect_address: "< Flipt URL with no path >" scopes: - "user:email" ``` -The `client_id` and `client_secret` are going to be the values from your GitHub OAuth application. The `redirect_address` will be the `ngrok` URL with no path (e.g. `https://36f1-2600-1700-1d64-daa0-444c-3f7e-ceb7-3825.ngrok-free.app`). The `scopes` are entirely dependent on what level of access you would like the returned GitHub access token to have. The [GitHub documentation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) describes a list of valid scopes. +The `client_id` and `client_secret` are going to be the values from your GitHub OAuth application. The `redirect_address` will be `http://localhost:8080`. The `scopes` are entirely dependent on what level of access you would like the returned GitHub access token to have. The [GitHub documentation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) describes a list of valid scopes. -The last bit of configuration is the session details. In order for the browser to establish a session to communicate with Flipt in an authenticated way, you must provide access details in an HTTP cookie whose value is a static token created by Flipt. This static token is created during the GitHub OAuth 2.0 flow, and associated with the GitHub metadata retrieved from the GitHub API with the access token. The `domain` value will specify which host can receive the cookie. Since we only care about the host serving Flipt, you can provide the `ngrok` URL value but without the `https://` prefix (e.g. `36f1-2600-1700-1d64-daa0-444c-3f7e-ceb7-3825.ngrok-free.app`). +The last bit of configuration is the session details. In order for the browser to establish a session to communicate with Flipt in an authenticated way, you must provide access details in an HTTP cookie whose value is a static token created by Flipt. This static token is created during the GitHub OAuth 2.0 flow, and associated with the GitHub metadata retrieved from the GitHub API with the access token. The `domain` value will specify which host can receive the cookie. ### 2. Run Flipt as a Docker container @@ -103,7 +96,7 @@ This will mount the `config.yml` as a volume in the container, and Flipt will us ### 3. Navigate to the Flipt UI -Access the Flipt UI by typing in the `ngrok` URL in the address bar of a browser. You should see the following screen: +Access the Flipt UI by typing in the `http://localhost:8080` URL in the address bar of a browser. You should see the following screen: ![Login With GitHub](/images/guides/login-with-github/login-with-github.png) @@ -117,8 +110,8 @@ Click on the green `Authorize {username}` button to allow completion of the OAut After completion of the flow you should be taken to the normal Flipt homepage and start using Flipt normally as before. If you have a profile picture on GitHub, it should show in the top right corner. -![Flipt Dashboard](/images/guides/login-with-github/flipt-homepage.png) +![Flipt Dashboard](/images/guides/login-with-github/flipt-dashboard.png) -This guide shows the basics of getting Flipt running with GitHub OAuth 2.0 authentication in a development setting using `ngrok`. +This guide shows the basics of getting Flipt running with GitHub OAuth 2.0 authentication in a development. -Now that you know the basics, you can tailor the configuration pieces to fit your exact use cases. For instance, you would not use `ngrok` in a production setting, but rather a custom domain. If you have a custom domain, you can modify the `Authorization Callback URL` value on the GitHub OAuth application page, the `redirect_address`, and `domain` configuration values for the Flipt configuration. +Now that you know the basics, you can tailor the configuration pieces to fit your exact use cases. For instance, you would not use `localhost:8080` in a production setting, but rather a custom domain. If you have a custom domain, you can modify the `Authorization Callback URL` value on the GitHub OAuth application page, the `redirect_address`, and `domain` configuration values for the Flipt configuration.