permissions

About permissions

This large README is shown as a plain-text preview. Read the full README at the source

# Permissions 3

[![Build](https://github.com/xyproto/permissions/actions/workflows/build.yml/badge.svg)](https://github.com/xyproto/permissions/actions/workflows/build.yml)
[![GoDoc](https://godoc.org/github.com/xyproto/permissions?status.svg)](http://godoc.org/github.com/xyproto/permissions)

Middleware for keeping track of users, login states and permissions.

This is the continuation of [permissions2](https://github.com/xyproto/permissions2), but with a simpler import string.

## Online API Documentation

[godoc.org](http://godoc.org/github.com/xyproto/permissions)

## Features and limitations

* Uses secure cookies and stores user information in a Redis database.
* Suitable for running a local Redis server, registering/confirming users and managing public/user/admin pages.
* Also supports connecting to remote Redis servers.
* Does not support SQL databases. For MariaDB/MySQL support, look into [permissionsql](https://github.com/xyproto/permissionsql).
* For Bolt database support (no database host needed, uses a file), look into [permissionbolt](https://github.com/xyproto/permissionbolt).
* For PostgreSQL database support (using the HSTORE feature), look into [pstore](https://github.com/xyproto/pstore).
* Supports registration and confirmation via generated confirmation codes.
* Tries to keep things simple.
* Only supports *public*, *user* and *admin* permissions out of the box, but offers functionality for implementing more fine grained permissions, if so desired.
* The default permissions can be cleared with the `Clear()` function.
* Supports [Chi](https://github.com/go-chi/chi), [Negroni](https://github.com/urfave/negroni), [Martini](https://github.com/go-martini/martini), [Gin](https://github.com/gin-gonic/gin), [Goji](https://github.com/zenazn/goji) and plain `net/http`.
* Should also work with other frameworks, since the standard `http.HandlerFunc` is used everywhere.

## Requirements

* Redis >= 2.6.12 (or an open source Redis clone)
* Go >= 1.21

## Examples

There is more information after the examples.

### Example for [Chi](https://github.com/go-chi/chi)

~~~ go
package main

import (
    "fmt"
    "log"
    "net/http"
    "strings"

    "github.com/go-chi/chi/v5"
    "github.com/xyproto/permissions"
)

func main() {
    m := chi.NewRouter()

    // New permissions middleware
    perm, err := permissions.New2()
    if err != nil {
        log.Fatalln(err)
    }

    // Blank slate, no default permissions
    //perm.Clear()

    // Get the userstate, used in the handlers below
    userstate := perm.UserState()

    // Set up the middleware handler for Chi
    m.Use(perm.Middleware)

    m.Get("/", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprintf(w, "Has user bob: %v\n", userstate.HasUser("bob"))
        fmt.Fprintf(w, "Logged in on server: %v\n", userstate.IsLoggedIn("bob"))
        fmt.Fprintf(w, "Is confirmed: %v\n", userstate.IsConfirmed("bob"))
        fmt.Fprintf(w, "Username stored in cookies (or blank): %v\n", userstate.Username(req))
        fmt.Fprintf(w, "Current user is logged in, has a valid cookie and *user rights*: %v\n", userstate.UserRights(req))
        fmt.Fprintf(w, "Current user is logged in, has a valid cookie and *admin rights*: %v\n", userstate.AdminRights(req))
        fmt.Fprintf(w, "\nTry: /register, /confirm, /remove, /login, /logout, /makeadmin, /clear, /data and /admin")
    })

    m.Get("/register", func(w http.ResponseWriter, r *http.Request) {
        userstate.AddUser("bob", "hunter1", "[email protected]")
        fmt.Fprintf(w, "User bob was created: %v\n", userstate.HasUser("bob"))
    })

    m.Get("/confirm", func(w http.ResponseWriter, r *http.Request) {
        userstate.MarkConfirmed("bob")
        fmt.Fprintf(w, "User bob was confirmed: %v\n", userstate.IsConfirmed("bob"))
    })

    m.Get("/remove", func(w http.ResponseWriter, r *http.Request) {
        userstate.RemoveUser("bob")
        fmt.Fprintf(w, "User bob was removed: %v\n", !userstate.HasUser("bob"))
    })

    m.Get("/login", func(w http.ResponseWriter, r *http.Request) {
        userstate.Login(w, "bob")
        fmt.Fprintf(w, "bob is now logged in: %v\n", userstate.IsLoggedIn("bob"))
    })

    m.Get("/logout", func(w http.ResponseWriter, r *http.Request) {
        userstate.Logout("bob")
        fmt.Fprintf(w, "bob is now logged out: %v\n", !userstate.IsLoggedIn("bob"))
    })

    m.Get("/makeadmin", func(w http.ResponseWriter, r *http.Request) {
        userstate.SetAdminStatus("bob")
        fmt.Fprintf(w, "bob is now administrator: %v\n", userstate.IsAdmin("bob"))
    })

    m.Get("/clear", func(w http.ResponseWriter, r *http.Request) {
        userstate.ClearCookie(w)
        fmt.Fprintf(w, "Clearing cookie")
    })

    m.Get("/data", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "user page that only logged in users must see!")
    })

    m.Get("/admin", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "super secret information that only logged in administrators must see!\n\n")
        if usernames, err := userstate.AllUsernames(); err == nil {
            fmt.Fprintf(w, "list of all users: "+strings.Join(usernames, ", "))
        }
    })

    // Custom handler for when permissions are denied
    perm.SetDenyFunction(func(w http.ResponseWriter, req *http.Request) {
        http.Error(w, "Permission denied!", http.StatusForbidden)
    })

    // Serve
    http.ListenAndServe(":3000", m)
}
~~~

### Example for [Negroni](https://github.com/urfave/negroni)

~~~ go
package main

import (
    "fmt"
    "net/http"
    "strings"
    "log"

    "github.com/urfave/negroni"
    "github.com/xyproto/permissions"
)

func main() {
    n := negroni.Classic()
    mux := http.NewServeMux()

    // New permissions middleware
    perm, err := permissions.New2()
    if err != nil {
        log.Fatalln(err)
    }

    // Blank slate, no default permissions
    //perm.Clear()

    // Get the userstate, used in the handlers below
    userstate := perm.UserState()

    mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprintf(w, "Has user bob: %v\n", userstate.HasUser("bob"))
        fmt.Fprintf(w, "Logged in on server: %v\n", userstate.IsLoggedIn("bob"))
        fmt.Fprintf(w, "Is confirmed: %v\n", userstate.IsConfirmed("bob"))
        fmt.Fprintf(w, "Username stored in cookies (or blank): %v\n", userstate.Username(req))
        fmt.Fprintf(w, "Current user is logged in, has a valid cookie and *user rights*: %v\n", userstate.UserRights(req))
        fmt.Fprintf(w, "Current user is logged in, has a valid cookie and *admin rights*: %v\n", userstate.AdminRights(req))
        fmt.Fprintf(w, "\nTry: /register, /confirm, /remove, /login, /logout, /makeadmin, /clear, /data and /admin")
    })

    mux.HandleFunc("/register", func(w http.ResponseWriter, req *http.Request) {
        userstate.AddUser("bob", "hunter1", "[email protected]")
        fmt.Fprintf(w, "User bob was created: %v\n", userstate.HasUser("bob"))
    })

    mux.HandleFunc("/confirm", func(w http.ResponseWriter, req *http.Request) {
        userstate.MarkConfirmed("bob")
        fmt.Fprintf(w, "User bob was confirmed: %v\n", userstate.IsConfirmed("bob"))
    })

    mux.HandleFunc("/remove", func(w http.ResponseWriter, req *http.Request) {
        userstate.RemoveUser("bob")
        fmt.Fprintf(w, "User bob was removed: %v\n", !userstate.HasUser("bob"))
    })

    mux.HandleFunc("/login", func(w http.ResponseWriter, req *http.Request) {
        userstate.Login(w, "bob")
        fmt.Fprintf(w, "bob is now logged in: %v\n", userstate.IsLoggedIn("bob"))
    })

    mux.HandleFunc("/logout", func(w http.ResponseWriter, req *http.Request) {
        userstate.Logout("bob")
        fmt.Fprintf(w, "bob is now logged out: %v\n", !userstate.IsLoggedIn("bob"))
    })

    mux.HandleFunc("/makeadmin", func(w http.ResponseWriter, req *http.Request) {
        userstate.SetAdminStatus("bob")
        fmt.Fprintf(w, "bob is now administrator: %v\n", userstate.IsAdmin("bob"))
    })

    mux.HandleFunc("/clear", func(w http.ResponseWriter, req *http.Request) {
        userstate.ClearCookie(w)
        fmt.Fprintf(w, "Clearing cookie")
    })

    mux.HandleFunc("/data", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprintf(w, "user page that only logged in users must see!")
    })

    mux.HandleFunc("/admin", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprintf(w, "super secret information that only logged in administrators must see!\n\n")
        if usernames, err := userstate.AllUsernames(); err == nil {
            fmt.Fprintf(w, "list of all users: "+strings.Join(usernames, ", "))
        }
    })

    // Custom handler for when permissions are denied
    perm.SetDenyFunction(func(w http.ResponseWriter, req *http.Request) {
        http.Error(w, "Permission denied!", http.StatusForbidden)
    })

    // Enable the permissions middleware
    n.Use(perm)

    // Use mux for routing, this goes last
    n.UseHandler(mux)

    // Serve
    n.Run(":3000")
}
~~~

### Example for [Martini](https://github.com/go-martini/martini)

~~~ go
package main

import (
    "fmt"
    "net/http"
    "strings"
    "log"

    "github.com/go-martini/martini"
    "github.com/xyproto/permissions"
)

func main() {
    m := martini.Classic()

    // New permissions middleware
    perm, err := permissions.New2()
    if err != nil {
        log.Fatalln(err)
    }

    // Blank slate, no default permissions
    //perm.Clear()

    // Get the userstate, used in the handlers below
    userstate := perm.UserState()

    m.Get("/", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprintf(w, "Has user bob: %v\n", userstate.HasUser("bob"))
        fmt.Fprintf(w, "Logged in on server: %v\n", userstate.IsLoggedIn("bob"))
        fmt.Fprintf(w, "Is confirmed: %v\n", userstate.IsConfirmed("bob"))
        fmt.Fprintf(w, "Username stored in cookies (or blank): %v\n", userstate.Username(req))
        fmt.Fprintf(w, "Current user is logged in, has a valid cookie and *user rights*: %v\n", userstate.UserRights(req))
        fmt.Fprintf(w, "Current user is logged in, has a valid cookie and *admin rights*: %v\n", userstate.AdminRights(req))
        fmt.Fprintf(w, "\nTry: /register, /confirm, /remove, /login, /logout, /makeadmin, /clear, /data and /admin")
    })

    m.Get("/register", func(w http.ResponseWriter) {
        userstate.AddUser("bob", "hunter1", "[email protected]")
        fmt.Fprintf(w, "User bob was created: %v\n", userstate.HasUser("bob"))
    })

    m.Get("/confirm", func(w http.ResponseWriter) {
        userstate.MarkConfirmed("bob")
        fmt.Fprintf(w, "User bob was confirmed: %v\n", userstate.IsConfirmed("bob"))
    })

    m.Get("/remove", func(w http.ResponseWriter) {
        userstate.RemoveUser("bob")
        fmt.Fprintf(w, "User bob was removed: %v\n", !userstate.HasUser("bob"))
    })

    m.Get("/login", func(w http.ResponseWriter) {
        userstate.Login(w, "bob")
        fmt.Fprintf(w, "bob is now logged in: %v\n", userstate.IsLoggedIn("bob"))
    })

    m.Get("/logout", func(w http.ResponseWriter) {
        userstate.Logout("bob")
        fmt.Fprintf(w, "bob is now logged out: %v\n", !userstate.IsLoggedIn("bob"))
    })

    m.Get("/makeadmin", func(w http.ResponseWriter) {
        userstate.SetAdminStatus("bob")
        fmt.Fprintf(w, "bob is now administrator: %v\n", userstate.IsAdmin("bob"))
    })

    m.Get("/clear", func(w http.ResponseWriter) {
        userstate.ClearCookie(w)
        fmt.Fprintf(w, "Clearing cookie")
    })

    m.Get("/data", func(w http.ResponseWriter) {
        fmt.Fprintf(w, "user page that only logged in users must see!")
    })

    m.Get("/admin", func(w http.ResponseWriter) {
        fmt.Fprintf(w, "super secret information that only logged in administrators must see!\n\n")
        if usernames, err := userstate.AllUsernames(); err == nil {
            fmt.Fprintf(w, "list of all users: "+strings.Join(usernames, ", "))
        }
    })

    // Set up a middleware handler for Martini, with a custom "permission denied" message.
    permissionHandler := func(w http.ResponseWriter, req *http.Request, c martini.Context) {
        // Check if the user has the right admin/user rights
        if perm.Rejected(w, req) {
            // Deny the request
            http.Error(w, "Permission denied!", http.StatusForbidden)
            // Reject the request by not calling the next handler below
            return
        }
        // Call the next middleware handler
        c.Next()
    }

    // Enable the permissions middleware
    m.Use(permissionHandler)

    // Serve
    m.Run()
}
~~~

### Example for [Gin](https://github.com/gin-gonic/gin)

~~~ go
package main

import (
    "fmt"
    "net/http"
    "strings"
    "log"

    "github.com/gin-gonic/gin"
    "github.com/xyproto/permissions"
)

func main() {
    g := gin.New()

    // New permissions middleware
    perm, err := permissions.New2()
    if err != nil {
        log.Fatalln(err)
    }

    // Blank slate, no default permissions
    //perm.Clear()

    // Set up a middleware handler for Gin, with a custom "permission denied" message.
    permissionHandler := func(c *gin.Context) {
        // Check if the user has the right admin/user rights
        if perm.Rejected(c.Writer, c.Request) {
            // Deny the request, don't call other middleware handlers
            c.AbortWithStatus(http.StatusForbidden)
            fmt.Fprint(c.Writer, "Permission denied!")
            return
        }
        // Call the next middleware handler
        c.Next()
    }

    // Logging middleware
    g.Use(gin.Logger())

    // Enable the permissions middleware, must come before recovery
    g.Use(permissionHandler)

    // Recovery middleware
    g.Use(gin.Recovery())

    // Get the userstate, used in the handlers below
    userstate := perm.UserState()

    g.GET("/", func(c *gin.Context) {
        msg := ""
        msg += fmt.Sprintf("Has user bob: %v\n", userstate.HasUser("bob"))
        msg += fmt.Sprintf("Logged in on server: %v\n", userstate.IsLoggedIn("bob"))
        msg += fmt.Sprintf("Is confirmed: %v\n", userstate.IsConfirmed("bob"))
        msg += fmt.Sprintf("Username stored in cookies (or blank): %v\n", userstate.Username(c.Request))
        msg += fmt.Sprintf("Current user is logged in, has a valid cookie and *user rights*: %v\n", userstate.UserRights(c.Request))
        msg += fmt.Sprintf("Current user is logged in, has a valid cookie and *admin rights*: %v\n", userstate.AdminRights(c.Request))
        msg += fmt.Sprintln("\nTry: /register, /confirm, /remove, /login, /logout, /makeadmin, /clear, /data and /admin")
        c.String(http.StatusOK, msg)
    })

    g.GET("/register", func(c *gin.Context) {
        userstate.AddUser("bob", "hunter1", "[email protected]")
        c.String(http.StatusOK, fmt.Sprintf("User bob was created: %v\n", userstate.HasUser("bob")))
    })

    g.GET("/confirm", func(c *gin.Context) {
        userstate.MarkConfirmed("bob")
        c.String(http.StatusOK, fmt.Sprintf("User bob was confirmed: %v\n", userstate.IsConfirmed("bob")))
    })

    g.GET("/remove", func(c *gin.Context) {
        userstate.RemoveUser("bob")
        c.String(http.StatusOK, fmt.Sprintf("User bob was removed: %v\n", !userstate.HasUser("bob")))
    })

    g.GET("/login", func(c *gin.Context) {
        // Headers will be written, for storing a cookie
        userstate.Login(c.Writer, "bob")
        c.String(http.StatusOK, fmt.Sprintf("bob is now logged in: %v\n", userstate.IsLoggedIn("bob")))
    })

    g.GET("/logout", func(c *gin.Context) {
        userstate.Logout("bob")
        c.String(http.StatusOK, fmt.Sprintf("bob is now logged out: %v\n", !userstate.IsLoggedIn("bob")))
    })

    g.GET("/makeadmin", func(c *gin.Context) {
        userstate.SetAdminStatus("bob")
        c.String(http.StatusOK, fmt.Sprintf("bob is now administrator: %v\n", userstate.IsAdmin("bob")))
    })

    g.GET("/clear", func(c *gin.Context) {
        userstate.ClearCookie(c.Writer)
        c.String(http.StatusOK, "Clearing cookie")
    })

    g.GET("/data", func(c *gin.Context) {
        c.String(http.StatusOK, "user page that only logged in users must see!")
    })

    g.GET("/admin", func(c *gin.Context) {
        c.String(http.StatusOK, "super secret information that only logged in administrators must see!\n\n")
        if usernames, err := userstate.AllUsernames(); err == nil {
            c.String(http.StatusOK, "list of all users: "+strings.Join(usernames, ", "))
        }
    })

    // Serve
    g.Run(":3000")
}
~~~

### Example for [Goji](https://github.com/zenazn/goji)

~~~ go
package main

import (
    "fmt"
    "net/http"
    "strings"
    "log"

    "github.com/xyproto/permissions"
    "github.com/zenazn/goji"
)

func main() {
    // New permissions middleware
    perm, err := permissions.New2()
    if err != nil {
        log.Fatalln(err)
    }

    // Blank slate, no default permissions
    //perm.Clear()

    // Get the userstate, used in the handlers below
    userstate := perm.UserState()

    goji.Get("/", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprintf(w, "Has user bob: %v\n", userstate.HasUser("bob"))
        fmt.Fprintf(w, "Logged in on server: %v\n", userstate.IsLoggedIn("bob"))
        fmt.Fprintf(w, "Is confirmed: %v\n", userstate.IsConfirmed("bob"))
        fmt.Fprintf(w, "Username stored in cookies (or blank): %v\n", userstate.Username(req))
        fmt.Fprintf(w, "Current user is logged in, has a valid cookie and *user rights*: %v\n", userstate.UserRights(req))
        fmt.Fprintf(w, "Current user is logged in, has a valid cookie and *admin rights*: %v\n", userstate.AdminRights(req))
        fmt.Fprintf(w, "\nTry: /register, /confirm, /remove, /login, /logout, /makeadmin, /clear, /data and /admin")
    })

    goji.Get("/register", func(w http.ResponseWriter, req *http.Request) {
        userstate.AddUser("bob", "hunter1", "[email protected]")
        fmt.Fprintf(w, "User bob was created: %v\n", userstate.HasUser("bob"))
    })

    goji.Get("/confirm", func(w http.ResponseWriter, req *http.Request) {
        userstate.MarkConfirmed("bob")
        fmt.Fprintf(w, "User bob was confirmed: %v\n", userstate.IsConfirmed("bob"))
    })

    goji.Get("/remove", func(w http.ResponseWriter, req *http.Request) {
        userstate.RemoveUser("bob")
        fmt.Fprintf(w, "User bob was removed: %v\n", !userstate.HasUser("bob"))
    })

    goji.Get("/login", func(w http.ResponseWriter, req *http.Request) {
        userstate.Login(w, "bob")
        fmt.Fprintf(w, "bob is now logged in: %v\n", userstate.IsLoggedIn("bob"))
    })

    goji.Get("/logout", func(w http.ResponseWriter, req *http.Request) {
        userstate.Logout("bob")
        fmt.Fprintf(w, "bob is now logged out: %v\n", !userstate.IsLoggedIn("bob"))
    })

    goji.Get("/makeadmin", func(w http.ResponseWriter, req *http.Request) {
        userstate.SetAdminStatus("bob")
        fmt.Fprintf(w, "bob is now administrator: %v\n", userstate.IsAdmin("bob"))
    })

    goji.Get("/clear", func(w http.ResponseWriter, req *http.Request) {
        userstate.ClearCookie(w)
        fmt.Fprintf(w, "Clearing cookie")
    })

    goji.Get("/data", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprintf(w, "user page that only logged in users must see!")
    })

    goji.Get("/admin", func(w http.ResponseWriter, req *http.Request) {
        fmt.Fprintf(w, "super secret information that only logged in administrators must see!\n\n")
        if usernames, err := userstate.AllUsernames(); err == nil {
            fmt.Fprintf(w, "list of all users: "+strings.Join(usernames, ", "))
        }
    })

    // Custom "permissions denied" message
    perm.SetDenyFunction(func(w http.ResponseWriter, req *http.Request) {
        http.Error(w, "Permission denied!", http.StatusForbidden)
    })

Frequently Asked Questions