Add documentation for running Keycloak

Ref #691

Makefile

@@ -147,4 +147,6 @@ dbschema:	## generate database schema with schema spy, monitor file until doc is
 
 mock:  ## generate mocks
 	mockgen -package mockdb -destination database/mock/store.go github.com/stacklok/mediator/internal/db Store
-	mockgen -package mockgh -destination internal/providers/github/mock/github.go -source pkg/providers/v1/providers.go GitHub 
+	mockgen -package mockgh -destination internal/providers/github/mock/github.go -source pkg/providers/v1/providers.go GitHub
+	mockgen -package auth -destination internal/auth/mock/jwtauth.go github.com/stacklok/mediator/internal/auth JwtValidator,KeySetFetcher
+

README.md

@@ -172,6 +172,10 @@ To generate the mocks, run:
 ```bash
 mockgen -package mockdb -destination database/mock/store.go github.com/stacklok/mediator/internal/db Store
 ```
+and
+```bash
+mockgen -package auth -destination internal/auth/mock/jwtauth.go github.com/stacklok/mediator/internal/auth JwtValidator,KeySetFetcher
+```
 
 # Configuration
 
@@ -183,6 +187,39 @@ Most values should be quite self explanatory.
 
 Before running the app, please copy the content of `config/config.yaml.example` into `$PWD/config.yaml` file, and modify to use your own settings.
 
+## Social login configuration
+_note: this will be improved in the future, to avoid modifying the Keyclaok JSON file_  
+
+You can optionally configure login with GitHub by modifying the Keycloak configuration file.
+
+You may create an OAuth2 application for GitHub [here](https://github.com/settings/developers). Select
+`New OAuth App` and fill in the details. The callback URL should be `http://localhost:8081/realms/stacklok/broker/github/endpoint`.
+Create a new client secret for your OAuth2 client.
+
+Then, in the file `identity/import/stacklok-realm-with-user-and-client.json`, replace `identityProviders" : [ ],` with the following, using your generated client ID and client secret:
+```
+”identityProviders" : [
+  {
+  "alias" : "github",
+  "internalId" : "afb4fd44-b6d7-4cff-a4ff-12735ca09b02",
+  "providerId" : "github",
+  "enabled" : true,
+  "updateProfileFirstLoginMode" : "on",
+  "trustEmail" : false,
+  "storeToken" : false,
+  "addReadTokenRoleOnCreate" : false,
+  "authenticateByDefault" : false,
+  "linkOnly" : false,
+  "firstBrokerLoginFlowAlias" : "first broker login",
+  "config" : {
+    "clientSecret" : "the-client-secret-you-generated",
+    "clientId" : "the-client-id-you-generated"
+  }
+ }
+],
+```
+Restart the Keycloak instance if it is already running.
+
 # Initial setup / Getting started
 
 ## Login
@@ -226,13 +263,8 @@ repositories table with the repositories you have access to.
 Now that you've granted the GitHub app permissions to access your repositories, you can register them:
 
 ```bash
-go run ./cmd/cli/main.go repo register -n github -g 1
+go run ./cmd/cli/main.go repo register -n github
 ```
 
-You're probably wondering why you need to pass the `-g` flag. This is because the repositories are registered
-under a group. This is to allow for multiple repositories to be registered under the same group. In the future,
-you might create different groups for different purposes. For example, you might have a group for your personal
-repositories, and another group for your work repositories.
-
 Once you've registered the repositories, the mediator server will listen for events from GitHub and will
 automatically create the necessary webhooks for you.

docs/docs/getting_started/login_medic.md

@@ -15,10 +15,12 @@ displayed_sidebar: mediator
 1. Log in with username and password.  By default, `medic` will run against a public stacklok cloud instance, but this can be changed in `config.yaml` in your local directory or using the `--gprc-host` and `--grpc-port` flags.
 
 ```bash
-medic auth login --username  <username> --password <password>
+medic auth login
 ```
 
-Once logged
+A new browser window will open, where you can register a new user and log in.
+
+Once logged in
 
 2. Enroll a user with the given provider
 

docs/docs/run_mediator_server/run_the_server.md

@@ -8,14 +8,16 @@ displayed_sidebar: mediator
 
 # Run a mediator server
 
-Mediator is platform, comprising of a controlplane, a CLI and a database.
+Mediator is platform, comprising of a controlplane, a CLI, a database and an identity provider.
 
 The control plane runs two endpoints, a gRPC endpoint and a HTTP endpoint.
 
 Mediator is controlled and managed via the CLI application `medic`.
 
 PostgreSQL is used as the database.
 
+Keycloak is used as the identity provider.
+
 There are two methods to get started with Mediator, either by downloading the
 latest release, building from source or (quickest) using the provided `docker-compose`
 file.
@@ -24,6 +26,7 @@ file.
 
 - [Go 1.20](https://golang.org/doc/install)
 - [PostgreSQL](https://www.postgresql.org/download/)
+- [Keycloak](https://www.keycloak.org/guides)
 
 ## Download the latest release
 
@@ -92,6 +95,30 @@ or:
 mediator-server migrate up
 ```
 
+# Identity Provider
+Mediator requires a Keycloak instance to be running. You can install this locally, or use a container.
+
+Should you install locally, you will need to configure the client on Keycloak.
+You will need the following:
+- A Keycloak realm where the mediator client can be registered
+- A registered client with the redirect URI `http://localhost/*`
+
+You will also need to set certain configuration options in your `config.yaml` file, to reflect your local Keycloak configuration.
+```yaml
+identity:
+  issuer_url: http://localhost:8081
+  realm: stacklok
+  client_id: mediator-cli
+```
+
+### Using a container
+
+A simple way to get started is to use the provided `docker-compose` file.
+
+```bash
+docker-compose up -d keycloak
+```
+
 ## Create encryption keys
 
 The default configuration expects these keys to be in a directory named `.ssh`, relative to where you run the `mediator-server` binary.
@@ -101,7 +128,7 @@ Start by creating the `.ssh` directory.
 mkdir .ssh && cd .ssh
 ```
 
-Encryption keys are used to encrypt JWT tokens. You can create these using the `openssl` CLI tool.
+You can create the encryption keys using the `openssl` CLI tool.
 
 ```bash
 # First generate an RSA key pair