feat: v1 readme, refactored some names

Author: tallen42

README.md

@@ -5,44 +5,36 @@ An @ComputerScienceHouse authentication wrapper for Gin.
 
 ## Usage
 
-1. Create a CSHAuth Struct
-
-```
-csh := csh_auth.CSHAuth{}
-```
-
-2. Initialize your CSHAuth object
-
-```
-csh.Init(
-    /* oidc_client_id */,       // The OIDC client ID
-    /* oidc_client_secret */,   // The OIDC client Secret
-    /* jwt_secret */,           // I just used a random sequence of > 16 characters
-    /* state */,                // I just used a random sequence of > 16 characters
-    /* server_host */,          // The domain your application will run from
-    /* redirect_uri */,         // The OIDC redirect URI
-    /* auth_uri */,             // The relative path for your authentication endpoint
+1. Initialize your csh-auth object
+
+```
+auth := csh-auth.Init(
+    clientID            // the OIDC client ID
+    clientSecret        // the OIDC client secret
+    serverURL           // the "base" URL that this service is hosted from, e.g. "http://localhost:8000"
+    loginURL            // the URL for users to start the OAuth flow and login.
+                        // Commonly, this is set to something like ServerHost+"/auth/login"
+    callbackURL         // the URL that users will be redirected to at the end of the OAuth flow.
+                        // Commonly, this is set to something like ServerHost+"/auth/callback"
+    scopes              // pick scopes the application will use
 )
 ```
 
-3. Add required CSHAuth endpoints
+2. Add csh-auth endpoints for user login
 
 ```
-r.GET("/auth/login", csh.AuthRequest) // This endpoint should match auth_uri
-r.GET("/auth/callback", csh.AuthCallback) // This endpoint should match the relative portion of redirect_uri
-r.GET("/auth/logout", csh.AuthLogout)
+r.GET("/auth/login", auth.HandleLogin) // This endpoint should match the path for loginURL
+r.GET("/auth/callback", auth.HandleCallback) // This endpoint should match the path for callbackURL
+r.GET("/auth/logout", auth.HandleLogout)
 ```
 
-4. Add endpoints to be behind authentication
-
-a. Use a wrapper function
-```
-r.GET("/hidden/prize", csh.AuthWrapper(endpoint_hidden_prize))
-```
+3. Add endpoints to be behind authentication
 
-b. Use middleware.
+For client authentication, use `auth.CookieMiddleware()`  
+For application authentication via Bearer tokens, use `auth.HeaderMiddleware()`.
+The HeaderMiddleware only accepts the `Authorization` header with the format `Bearer: <JWT AccessToken>`.
 
-For a single route: `r.GET("/hidden/prize", csh.AuthWrapper, endpoint_hidden_prize)`  
+For a single route: `r.GET("/locked/prize", auth.CookieMiddleware(), endpoint_hidden_prize)`  
 This works because Gin will run the widest scope function to the most narrow scope function, in order. 
 
 For more/all routes: Check the [Gin Middleware documentation](https://gin-gonic.com/en/docs/middleware/) page.

auth.go

@@ -29,9 +29,9 @@ type Auth struct {
 	clientSecret string
 	// serverURL is the "base" URL that this service is hosted from, e.g. "http://localhost:8000"
 	serverURL string
-	// authenticateURL is the URL for users to start the OAuth flow and login.
+	// loginURL is the URL for users to start the OAuth flow and login.
 	// Commonly, this is set to something like ServerHost+"/auth/login"
-	authenticateURL string
+	loginURL string
 	// callbackURL is the URL that users will be redirected to at the end of the OAuth flow.
 	// Commonly, this is set to something like ServerHost+"/auth/callback"
 	callbackURL string
@@ -56,14 +56,14 @@ type Claims struct {
 	UserInfo
 }
 
-func Init(oidcClientID string, oidcClientSecret string, serverURL string, authenticateURL string, callbackURL string, scopes []string) (Auth, error) {
+func Init(oidcClientID string, oidcClientSecret string, serverURL string, loginURL string, callbackURL string, scopes []string) (Auth, error) {
 	auth := Auth{
-		clientID:        oidcClientID,
-		clientSecret:    oidcClientSecret,
-		serverURL:       serverURL,
-		authenticateURL: authenticateURL,
-		callbackURL:     callbackURL,
-		ctx:             context.Background(),
+		clientID:     oidcClientID,
+		clientSecret: oidcClientSecret,
+		serverURL:    serverURL,
+		loginURL:     loginURL,
+		callbackURL:  callbackURL,
+		ctx:          context.Background(),
 	}
 
 	auth.secure = serverURL[0:5] == "https"
@@ -106,18 +106,18 @@ func (auth *Auth) HandleCallback(c *gin.Context) {
 	ref, err := c.Cookie("ref")
 	if err != nil {
 		log.Error("no callback ref cookie")
-		c.Redirect(http.StatusFound, auth.authenticateURL)
+		c.Redirect(http.StatusFound, auth.loginURL)
 		return
 	}
 	state, ok := StateLookup[ref]
 	if !ok {
 		log.Error("callback ref not found")
-		c.Redirect(http.StatusFound, auth.authenticateURL)
+		c.Redirect(http.StatusFound, auth.loginURL)
 		return
 	}
 	if c.Query("state") != state {
 		log.Error("state does not match")
-		c.Redirect(http.StatusFound, auth.authenticateURL)
+		c.Redirect(http.StatusFound, auth.loginURL)
 		return
 	}
 
@@ -131,14 +131,19 @@ func (auth *Auth) HandleCallback(c *gin.Context) {
 	c.Redirect(http.StatusFound, c.Query("referer"))
 }
 
+func (auth *Auth) HandleLogout(c *gin.Context) {
+	c.SetCookie(CookieName, "", 0, "", "", false, true)
+	c.Redirect(http.StatusFound, ProviderURI+"/protocol/openid-connect/logout?post_logout_redirect_uri="+auth.serverURL+"/&client_id="+auth.clientID+"")
+}
+
 // Middleware functions
 
 func (auth *Auth) CookieMiddleware() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		cookie, err := c.Cookie(CookieName)
 		if err != nil {
 			log.Error(CookieName, "cookie not found")
-			c.Redirect(http.StatusFound, auth.authenticateURL+"?referer="+c.Request.URL.String())
+			c.Redirect(http.StatusFound, auth.loginURL+"?referer="+c.Request.URL.String())
 			return
 		}
 		err = auth.setGinContext(c, cookie)