Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MustHave ¶
func MustHave(fn func(*gin.Context) (authenticated bool, groups Groups), rule Rule, more ...Rule) gin.HandlerFunc
MustHave returns a gin middleware that aborts the request with either http.StatusUnauthorized or http.StatusForbidden depending on whether there exists a user with the current session whose group membership satisfies the given rules.
The middleware must be given function fn that returns whether the session is authenticated (i.e. session exists with a valid user) and also retrieves the user's group from the current request. If session is not authenticated then the request is aborted with http.StatusUnauthorized (can be customised with WithUnauthorizedHandler). If the session is authenticated but the groups do not satisfy the rules, the request is aborted with http.StatusForbidden (can be customised with WithForbiddenHandler to provide a meaningful error message such as "user must belong to ABC group"). Otherwise, the request goes through unimpeded.
Usage:
type MySession struct {
SessionId string `dynamodbav:"sessionId,hashkey" tableName:"sessions"`
User *User `dynamodbav:"user,omitempty"`
}
type User struct {
Sub string `dynamodbav:"user"`
Groups []string `dynamodbav:"groups,stringset"
}
r := gin.Default()
r.Use(sessions.Session[MySession]("sid"))
r.GET(
"/protected/resource",
groups.MustHave(func (c *gin.Context) (bool, groups.Groups) {
var s *Session = sessions.Get[MySession](c)
if s.User == nil {
return false, nil
}
return true, s.User.Groups
}, groups.OneOf("readResource", "writeResource"))
Note that if you don't pass any OneOf or AllOf rule, so long as the session has a valid user (i.e. fn argument returns true as its first return value), the request will not be rejected.
Types ¶
type Groups ¶
type Groups []string
Groups is a string list, preferably a string set.
func (Groups) Test ¶
Test verifies that the user's groups satisfy the membership rules.
Use AllOf and/or OneOf to describe how to authorise the user's groups.
Usage:
// user must be able to read both payments and inventory.
Groups([]string{...}).Test(AllOf("can_read_payment", "can_read_inventory"))
// user must be able to read both payments and inventory, but write permissions implies read as well.
Groups([]string{...}).Test(OneOf("can_read_payment", "can_write_payment"), OneOf("can_read_inventory", "can_write_inventory"))
This function ignores WithUnauthorizedHandler and WithForbiddenHandler settings since it is intended to be used outside of a gin request. If you don't pass any OneOf or AllOf rule, the function always returns true.
type Rule ¶
type Rule func(*rules)
Rule can only be either AllOf or OneOf.
func OneOf ¶
OneOf adds a rule that the user must belong to at least one of the groups specified here.
func WithForbiddenHandler ¶ added in v0.1.6
func WithForbiddenHandler(f gin.HandlerFunc) Rule
WithForbiddenHandler can be used to customise the response when the session's user's groups do not satisfy the rules.
By default, gin.Context.AbortWithStatus is called passing http.StatusForbidden.
func WithUnauthorizedHandler ¶ added in v0.1.6
func WithUnauthorizedHandler(f gin.HandlerFunc) Rule
WithUnauthorizedHandler can be used to customise the response when the session has no user.
By default, gin.Context.AbortWithStatus is called passing http.StatusUnauthorized.
Source Files