add readme

Author: Patrick Koss

Makefile

@@ -19,7 +19,7 @@ build:
 
 .PHONY: docker-build
 docker-build:
-	CGO_ENABLED=0 go build -ldflags "-s -w" -o ./bin/fake-jwt-server -v cmd/fakejwtserver/main.go
+	GOOS=linux CGO_ENABLED=0 go build -ldflags "-s -w" -o ./fake-jwt-server -v cmd/fakejwtserver/main.go
 	docker build -t $(IMG) -f Dockerfile .
 	rm fake-jwt-server
 

README.md

@@ -1 +1,41 @@
-# fake-jwt-server
+# Introduction
+
+A straightforward mock-up of an identity provider (IDP) is designed to issue JWTs, enhancing the security of
+communications between services.
+
+![fake-jwt-server-illustration](./media/fake-jwt-illustration.png)
+
+To safeguard service interactions, various methods are available such as mutual TLS, basic authentication, or bearer
+authentication, to name a few. In bearer authentication, a token is required from an IDP, like Keycloak or Okta, through
+the client credentials grant of OAuth 2.0. Once the JWT is acquired, it can be transmitted in the authorization header
+when a service communicates with another. The recipient service can then verify the token using the IDP's public key.
+During local development or integration testing, utilizing a real IDP may not be desirable. This is where the concept of
+a fake-jwt-server is introduced. It's a basic version of an IDP that issues JWTs for OAuth flows and provides a public
+key endpoint for token verification.
+
+# Running the Server
+
+To launch the server in a Docker container, execute the following command:
+
+```bash
+docker run -p 8008:8008 ghcr.io/stackitcloud/fake-jwt-server:v0.1.0
+```
+
+This command initializes the server on port 8008. The public key can be accessed
+at http://localhost:8008/.well-known/jwks.json, and the OAuth token endpoint is available
+at http://localhost:8008/token.
+
+# Configuration
+
+The server's settings can be adjusted using specified environment variables and flags.
+
+| Environment Variable | Flag                   | Description                                                               |
+|----------------------|------------------------|---------------------------------------------------------------------------|
+| `PORT`               | `--port`               | The port the server listens on. Defaults to `8008`.                       |
+| `ISSUER`             | `--issuer`             | The issuer of the tokens. Defaults to `test`.                             |
+| `AUDIENCE`           | `--audience `          | The audience of the tokens. Defaults to `test `.                          |
+| `SUBJECT`            | `--subject`            | The subject of the tokens. Defaults to `test`                             |
+| `ID`                 | `--id`                 | The id of the tokens. Defaults to `test`.                                 |
+| `EXPIRES_IN_MINUTES` | `--expires-in-minutes` | The expiration time of the JWT tokens in minutes. Defaults to `52560000`. |
+| `GRAND_TYPE`         | `--grand-type`         | The grand type of the JWT tokens. Defaults to `client_credentials`.       |
+| `EMAIL`              | `--email`              | The email of the JWT token in minutes. Defaults to `test@example.com`.    |

cmd/fakejwtserver/cmd/root.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"log"
 	"strings"
+	"time"
 
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
@@ -13,11 +14,14 @@ import (
 )
 
 var (
-	audience string
-	issuer   string
-	subject  string
-	port     int
-	id       string
+	audience         string
+	issuer           string
+	subject          string
+	port             int
+	id               string
+	email            string
+	grandType        string
+	expiresInMinutes int
 )
 
 var rootCmd = &cobra.Command{
@@ -31,6 +35,9 @@ var rootCmd = &cobra.Command{
 		fakeJwtServer.WithSubject(subject)
 		fakeJwtServer.WithID(id)
 		fakeJwtServer.WithPort(port)
+		fakeJwtServer.WithEmail(email)
+		fakeJwtServer.WithGrandType(grandType)
+		fakeJwtServer.WithExpires(time.Duration(expiresInMinutes))
 
 		err := fakeJwtServer.Serve()
 		if err != nil {
@@ -46,11 +53,14 @@ func Execute() error {
 func init() {
 	cobra.OnInitialize(initConfig)
 
-	rootCmd.PersistentFlags().StringVar(&audience, "audience", "product", "The audience of the JWT token")
-	rootCmd.PersistentFlags().StringVar(&issuer, "issuer", "product", "The issuer of the JWT token")
+	rootCmd.PersistentFlags().StringVar(&audience, "audience", "test", "The audience of the JWT token")
+	rootCmd.PersistentFlags().StringVar(&issuer, "issuer", "test", "The issuer of the JWT token")
 	rootCmd.PersistentFlags().StringVar(&subject, "subject", "test", "The subject of the JWT token")
 	rootCmd.PersistentFlags().StringVar(&id, "id", "test", "The id of the JWT token")
 	rootCmd.PersistentFlags().IntVar(&port, "port", 8008, "The port the server should listen on")
+	rootCmd.PersistentFlags().StringVar(&email, "email", "test@example.com", "The email of the JWT token")
+	rootCmd.PersistentFlags().StringVar(&grandType, "grand-type", "client_credentials", "The grand type of the JWT token")
+	rootCmd.PersistentFlags().IntVar(&expiresInMinutes, "expires-in-minutes", 24*365*100*60, "The expiration time of the JWT token in minutes")
 }
 
 func initConfig() {

media/fake-jwt-illustration.png

@@ -141,19 +141,18 @@ type FakeClaims struct {
 }
 
 func (f *FakeJWTServer) createJsonWebToken() (string, error) {
-	const years = 100
 	claims := FakeClaims{
 		RegisteredClaims: jwt.RegisteredClaims{
 			Issuer:    f.config.Issuer,
 			Subject:   f.config.Subject,
 			Audience:  jwt.ClaimStrings{f.config.Audience},
-			ExpiresAt: jwt.NewNumericDate(time.Now().AddDate(years, 0, 0)),
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(f.config.Expires)),
 			NotBefore: jwt.NewNumericDate(time.Now().AddDate(0, 0, -1)),
 			IssuedAt:  jwt.NewNumericDate(time.Now()),
 			ID:        f.config.ID,
 		},
-		Email:     "test@stackit.cloud",
-		GrantType: "client_credentials",
+		Email:     f.config.Email,
+		GrantType: f.config.GrandType,
 	}
 	token := jwt.NewWithClaims(jwt.SigningMethodRS512, claims)
 	token.Header[jwk.KeyIDKey] = f.jsonWebKey.KeyID()
@@ -166,11 +165,14 @@ func (f *FakeJWTServer) createJsonWebToken() (string, error) {
 }
 
 type Config struct {
-	Issuer   string
-	Subject  string
-	Audience string
-	ID       string
-	Port     int
+	Issuer    string
+	Subject   string
+	Audience  string
+	ID        string
+	Port      int
+	Expires   time.Duration
+	Email     string
+	GrandType string
 }
 
 func NewFakeJwtServer() *FakeJWTServer {
@@ -194,11 +196,14 @@ func NewFakeJwtServer() *FakeJWTServer {
 		jsonWebKey:   jsonWebKey,
 		publicKeySet: publicKeySet,
 		config: Config{
-			Issuer:   "product",
-			Subject:  "test",
-			Audience: "product",
-			ID:       "test",
-			Port:     8008,
+			Issuer:    "test",
+			Subject:   "test",
+			Audience:  "test",
+			ID:        "test",
+			Port:      8008,
+			Expires:   24 * 365 * 100 * time.Hour,
+			Email:     "test@example.com",
+			GrandType: "client_credentials",
 		},
 	}
 }
@@ -233,6 +238,24 @@ func (f *FakeJWTServer) WithPort(port int) *FakeJWTServer {
 	return f
 }
 
+func (f *FakeJWTServer) WithExpires(expires time.Duration) *FakeJWTServer {
+	f.config.Expires = expires
+
+	return f
+}
+
+func (f *FakeJWTServer) WithEmail(email string) *FakeJWTServer {
+	f.config.Email = email
+
+	return f
+}
+
+func (f *FakeJWTServer) WithGrandType(grantType string) *FakeJWTServer {
+	f.config.GrandType = grantType
+
+	return f
+}
+
 func (f *FakeJWTServer) Serve() error {
 	mux := http.NewServeMux()
 	mux.HandleFunc("/token", f.TokenHandler)