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  ```