Skip to content

Commit

Permalink
fix(guides): clean up login with Github operation guide
Browse files Browse the repository at this point in the history 
- remove Ngrok as it isn't required
- fix the dashboard image
  • Loading branch information
@erka
erka committed Jun 5, 2024
1 parent ed87fdd commit 218771a
Showing 1 changed file with 10 additions and 17 deletions.
27 changes: 10 additions & 17 deletions guides/operation/authentication/login-with-github.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.

Check warning on line 37 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.

Raw Output:
{"message": "[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 37, "column": 27}}}, "severity": "WARNING"}

Check warning on line 37 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 37, "column": 53}}}, "severity": "WARNING"}

Check warning on line 37 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.

Raw Output:
{"message": "[Microsoft.GeneralURL] For a general audience, use 'address' rather than 'URL'.", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 37, "column": 72}}}, "severity": "WARNING"}

Check warning on line 37 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 37, "column": 129}}}, "severity": "WARNING"}

Check warning on line 37 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 37, "column": 132}}}, "severity": "WARNING"}

Check warning on line 37 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 37, "column": 188}}}, "severity": "WARNING"}

<Note>
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,

Check failure on line 40 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / lint 

Replace `·setting,⏎·` with `⏎··setting,`

Check warning on line 40 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Microsoft.We] Try to avoid using first-person plural like 'We'.

Raw Output:
{"message": "[Microsoft.We] Try to avoid using first-person plural like 'We'.", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 40, "column": 3}}}, "severity": "WARNING"}
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.
</Note>
Expand Down Expand Up @@ -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.

Check warning on line 82 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.FutureTense] Possible future tense.

Raw Output:
{"message": "[Openly.FutureTense] Possible future tense.", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 82, "column": 123}}}, "severity": "WARNING"}

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.

Check warning on line 84 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.SentenceLength] Write short sentences (less than 25 words).

Raw Output:
{"message": "[Openly.SentenceLength] Write short sentences (less than 25 words).", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 84, "column": 55}}}, "severity": "WARNING"}

Check warning on line 84 in guides/operation/authentication/login-with-github.mdx

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Openly.SentenceLength] Write short sentences (less than 25 words).

Raw Output:
{"message": "[Openly.SentenceLength] Write short sentences (less than 25 words).", "location": {"path": "guides/operation/authentication/login-with-github.mdx", "range": {"start": {"line": 84, "column": 252}}}, "severity": "WARNING"}

### 2. Run Flipt as a Docker container

Expand All @@ -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)

Expand All @@ -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.

0 comments on commit 218771a

Please sign in to comment.