Update guides to ensure proper perms

[prezha]

Summary

Update:

• 'Configure a Provider' guide to add required Email addresses (read only) GitHub Account permissions for keycloak to be able to get users' email address (see logs below for more details)
  • ref: https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#user-permissions-for-email-addresses
  • ref: https://docs.github.com/en/rest/users/emails?apiVersion=2022-11-28#list-email-addresses-for-the-authenticated-user
• 'Installing a Development version' guide to ensure user owns flags-config.yaml, .secrets and .ssh folders that might be first created by docker (as root) whist running make run-docker

before

$ docker logs keycloak_container --follow
...
2024-12-05 20:25:27,987 WARN  [org.keycloak.events] (executor-thread-8) type="IDENTITY_PROVIDER_LOGIN_ERROR", realmId="966968d9-1f40-4708-b4f7-db21a3dd378c", realmName="stacklok", clientId="minder-cli", userId="null", ipAddress="172.19.0.1", error="identity_provider_login_failure", code_id="38ba9a7a-7d6b-43e6-9b11-08204f3bb899"
2024-12-05 20:25:32,015 WARN  [org.keycloak.broker.oidc.AbstractOAuth2IdentityProvider] (executor-thread-2) Primary email endpoint returned an error (403): {"message":"Resource not accessible by integration","documentation_url":"https://docs.github.com/rest/users/emails#list-email-addresses-for-the-authenticated-user","status":"403"}
2024-12-05 20:25:32,015 ERROR [org.keycloak.broker.oidc.AbstractOAuth2IdentityProvider] (executor-thread-2) Failed to make identity provider oauth callback: org.keycloak.broker.provider.IdentityBrokerException: Profile could not be retrieved from the github endpoint
	at org.keycloak.social.github.GitHubIdentityProvider.doGetFederatedIdentity(GitHubIdentityProvider.java:159)
	at org.keycloak.broker.oidc.AbstractOAuth2IdentityProvider.getFederatedIdentity(AbstractOAuth2IdentityProvider.java:314)
	at org.keycloak.broker.oidc.AbstractOAuth2IdentityProvider$Endpoint.authResponse(AbstractOAuth2IdentityProvider.java:557)
	at org.keycloak.broker.oidc.AbstractOAuth2IdentityProvider$Endpoint$quarkusrestinvoker$authResponse_ab908fbdd086ee82e140d8a818c077362a2d04b4.invoke(Unknown Source)
	at org.jboss.resteasy.reactive.server.handlers.InvocationHandler.handle(InvocationHandler.java:29)
	at io.quarkus.resteasy.reactive.server.runtime.QuarkusResteasyReactiveRequestContext.invokeHandler(QuarkusResteasyReactiveRequestContext.java:141)
	at org.jboss.resteasy.reactive.common.core.AbstractResteasyReactiveContext.run(AbstractResteasyReactiveContext.java:147)
	at io.quarkus.vertx.core.runtime.VertxCoreRecorder$14.runWith(VertxCoreRecorder.java:635)
	at org.jboss.threads.EnhancedQueueExecutor$Task.doRunWith(EnhancedQueueExecutor.java:2516)
	at org.jboss.threads.EnhancedQueueExecutor$Task.run(EnhancedQueueExecutor.java:2495)
	at org.jboss.threads.EnhancedQueueExecutor$ThreadBody.run(EnhancedQueueExecutor.java:1521)
	at org.jboss.threads.DelegatingRunnable.run(DelegatingRunnable.java:11)
	at org.jboss.threads.ThreadLocalResettingRunnable.run(ThreadLocalResettingRunnable.java:11)
	at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
	at java.base/java.lang.Thread.run(Thread.java:1583)
Caused by: org.keycloak.broker.provider.IdentityBrokerException: Primary email could not be retrieved from the github endpoint
	at org.keycloak.social.github.GitHubIdentityProvider.searchEmail(GitHubIdentityProvider.java:189)
	at org.keycloak.social.github.GitHubIdentityProvider.doGetFederatedIdentity(GitHubIdentityProvider.java:154)
	... 14 more
Caused by: org.keycloak.broker.provider.IdentityBrokerException: Primary email could not be retrieved from the github endpoint
	at org.keycloak.social.github.GitHubIdentityProvider.searchEmail(GitHubIdentityProvider.java:171)
	... 15 more
...

$ ls -la
total 37288
drwxr-xr-x 24 prezha prezha     4096 Dec  5 09:03 .
drwxr-xr-x  3 prezha prezha       20 May  6  2024 ..
drwxr-xr-x  2 prezha prezha       71 Nov 11 20:59 bin
drwxr-xr-x  2 prezha prezha     4096 Oct 18 20:20 .boilerplates
-rw-r--r--  1 prezha prezha      800 Oct 18 20:20 buf.gen.yaml
-rw-r--r--  1 prezha prezha      153 Oct 18 20:20 buf.work.yaml
drwxr-xr-x  2 prezha prezha       60 Oct 18 20:20 .clusterfuzzlite
drwxr-xr-x  6 prezha prezha       58 May  6  2024 cmd
-rw-r--r--  1 prezha prezha     3219 Apr 21  2024 CODE_OF_CONDUCT.md
drwxr-xr-x  2 prezha prezha      183 Oct 18 20:20 config
-rw-r--r--  1 prezha prezha      255 Nov  8 21:08 config.yaml
-rw-r--r--  1 prezha prezha     3997 Oct 14 19:17 CONTRIBUTING.md
-rw-r--r--  1 prezha prezha 37885273 May 26  2024 coverage.out
drwxr-xr-x  6 prezha prezha       84 Oct 18 20:20 database
drwxr-xr-x  4 prezha prezha       39 Apr 21  2024 deployment
drwxr-xr-x  4 prezha prezha       36 May  6  2024 docker
-rw-r--r--  1 prezha prezha     5850 Dec  2 23:13 docker-compose.yaml
drwxr-xr-x  5 prezha prezha      198 Dec  4 22:03 docs
drwxr-xr-x  3 prezha prezha       65 Nov 11 20:47 examples
drwxr-xr-x  2 root   root          6 May 26  2024 flags-config.yaml
drwxr-xr-x  8 prezha prezha      220 Dec  5 18:29 .git
-rw-r--r--  1 prezha prezha      990 May  6  2024 .gitattributes
drwxr-xr-x  4 prezha prezha      117 Nov  6 18:22 .github
-rw-r--r--  1 prezha prezha      946 Aug 19 19:46 .gitignore
-rw-r--r--  1 prezha prezha     2885 Oct 18 20:20 .golangci.yml
-rw-r--r--  1 prezha prezha    19806 Dec  5 09:05 go.mod
-rw-r--r--  1 prezha prezha     3615 Oct 18 20:20 .goreleaser.yaml
-rw-r--r--  1 prezha prezha   151637 Dec  5 09:03 go.sum
drwxr-xr-x  4 prezha prezha       34 Apr 21  2024 identity
drwxr-xr-x 34 prezha prezha     4096 Dec  2 23:12 internal
-rw-r--r--  1 prezha prezha    11344 Apr 21  2024 LICENSE
-rw-r--r--  1 prezha prezha     2837 Sep 19 19:16 MAINTAINERS.md
-rw-r--r--  1 prezha prezha     1085 Oct 18 20:20 Makefile
drwxr-xr-x  2 prezha prezha      132 Nov  6 18:22 .mk
drwxr-xr-x 15 prezha prezha      210 Dec  2 23:12 pkg
drwxr-xr-x  3 prezha prezha       52 Nov  1 11:43 proto
-rw-r--r--  1 prezha prezha    11877 Nov  6 18:22 README.md
drwxr-xr-x  2 root   root          6 May 26  2024 .secrets
-rw-r--r--  1 prezha prezha     8532 Oct 14 19:17 SECURITY.md
-rw-r--r--  1 prezha prezha     3010 Apr 21  2024 server-config.yaml
-rw-r--r--  1 prezha prezha      679 Oct 18 20:20 sqlc.yaml
drwxr-xr-x  2 root   root          6 May 26  2024 .ssh
drwxr-xr-x  2 prezha prezha       50 Dec  5 18:26 tools
-rw-r--r--  1 prezha prezha      196 Dec  2 23:12 .trivyignore.yaml
-rw-r--r--  1 prezha prezha      323 Dec  2 23:12 .trivy.yml
drwxr-xr-x  4 prezha prezha      144 Nov  8 19:57 .trunk

Change Type

Mark the type of change your PR introduces:

• Bug fix (resolves an issue without affecting existing features)
• Feature (adds new functionality without breaking changes)
• Breaking change (may impact existing functionalities or require documentation updates)
• Documentation (updates or additions to documentation)
• Refactoring or test improvements (no bug fixes or new functionality)

Testing

Successfully tested locally.

Review Checklist:

• Reviewed my own code for quality and clarity.
• Added comments to complex or tricky code sections.
• Updated any affected documentation.
• Included tests that validate the fix or feature.
• Checked that related changes are merged.

[coveralls]

coverage: 55.212% (-0.003%) from 55.215%
when pulling ed7ac13 on prezha:docs-server
into b4fc9e3 on mindersec:main.