github.com/germla/auth@v0.0.0-20230505173936-bc9a4159cf17/authority/README.md (about) 1 # Authority 2 3 Authority is an authorization package for Golang. 4 5 When building web applications, we usually have requirements like verify current user has access to something or not, Authority could help you by providing HTTP middleware and helper method. 6 7 It is based on [Roles](http://github.com/qor/roles), means to define an ability, you need to register a role with `Roles`, refer [Roles](http://github.com/qor/roles) for how to do that. 8 9 ## Usage 10 11 ### Initialize Authority 12 13 Authority could use with [Auth](http://github.com/germla/auth) to get current user, handle sessions, you could use it, or implement your own [AuthInterface](http://godoc.org/github.com/germla/auth/authority#AuthInterface) 14 15 ```go 16 import ( 17 "github.com/germla/auth" 18 "github.com/germla/auth/authority" 19 "github.com/qor/roles" 20 ) 21 22 func main() { 23 Auth := auth.New(&auth.Config{}) 24 25 Authority := authority.New(&authority.Config{ 26 Auth: Auth, 27 Role: roles.Global, // default configuration 28 AccessDeniedHandler: func(w http.ResponseWriter, req *http.Request) { // redirect to home page by default 29 http.Redirect(w, req, "/", http.StatusSeeOther) 30 }, 31 }) 32 } 33 ``` 34 35 ## Defining Abilities 36 37 Refer [Roles](http://github.com/qor/roles) for how to use roles to register roles, here is a sample: 38 39 ```go 40 roles.Register("admin", func(req *http.Request, currentUser interface{}) bool { 41 return req.RemoteAddr == "127.0.0.1" || (currentUser.(*User) != nil && currentUser.(*User).Role == "admin") 42 }) 43 ``` 44 45 You might have some requirements like time based authorization, for example: 46 47 * I get distracted, come back to the site in 2 hours, then no access to my account details page, but still be able to visit shopping cart 48 * When place an order, I have to been authorized less than 60 minutes 49 50 Authority provides some [Rules](http://godoc.org/github.com/germla/auth/authority#Rule) to make you define them easily, used like: 51 52 ```go 53 Authority.Register("access_account_pages", authority.Rule{ 54 TimeoutSinceLastActive: 2 * time.Hour, 55 }) 56 57 Authority.Register("place_an_order", authority.Rule{ 58 TimeoutSinceLastAuth: time.Hour, 59 }) 60 ``` 61 62 ## Authorization Middleware 63 64 ```go 65 func main() { 66 mux := http.NewServeMux() 67 68 // Require current user has `access_account_pages` ability to acccess `AccountProfileHandler` 69 mux.Handle("/account/profile", Authority.Authorize("access_account_pages")(AccountProfileHandler)) 70 71 // Any logged user could acccess `AccountProfileHandler` if no roles specfied 72 mux.Handle("/account/profile", Authority.Authorize()(AccountProfileHandler)) 73 74 http.ListenAndServe(":9000", mux) 75 } 76 77 func AccountProfileHandler(w http.ResponseWriter, req *http.Request) { 78 // ... 79 } 80 ``` 81 82 ## Authorization Helper Method 83 84 ```go 85 func updateCreditCard(w http.ResponseWriter, req *http.Request) { 86 if Authority.Allow("place_an_order", req) { 87 // do something 88 } else { 89 // do something 90 } 91 } 92 ```