Using Basic Authentication

HTTP Basic Authentication is the simplest technique for enforcing access controls to web resources because it does not require cookies, session identifiers, or login pages; rather, HTTP Basic authentication uses standard fields in the HTTP header.

The Basic Authentication middleware is included with the Iris framework, so you do not need to install it separately.

1. Import the middleware

  1. import "github.com/kataras/iris/v12/middleware/basicauth"

2. Configure the middleware with its Options struct:

  1. opts := basicauth.Options{
  2.     Allow: basicauth.AllowUsers(map[string]string{
  3.         "username": "password",
  4.     }),
  5.     Realm:        "Authorization Required",
  6.     ErrorHandler: basicauth.DefaultErrorHandler,
  7.     // [...more options]
  8. }

3. Initialize the middleware:

  1. auth := basicauth.New(opts)

3.1 The above steps are the same as the Default function:

  1. auth := basicauth.Default(map[string]string{
  2.     "username": "password",
  3. })

3.2 Use a custom slice of Users:

  1. // The struct value MUST contain a Username and Passwords fields
  2. // or GetUsername() string and GetPassword() string methods.
  3. type User struct {
  4.     Username string
  5.     Password string
  6. }
  8. // [...]
  9. auth := basicauth.Default([]User{...})

3.3 Load users from a file optionally, passwords are encrypted using the golang.org/x/crypto/bcrypt package:

  1. auth := basicauth.Load("users.yml", basicauth.BCRYPT)

3.3.1 The same can be achieved using the Options (recommended):

  1. opts := basicauth.Options{
  2.     Allow: basicauth.AllowUsersFile("users.yml", basicauth.BCRYPT),
  3.     Realm: basicauth.DefaultRealm,
  4.     // [...more options]
  5. }
  7. auth := basicauth.New(opts)

Where the users.yml may look like that:

  1. - username: kataras
  2.   password: $2a$10$Irg8k8HWkDlvL0YDBKLCYee6j6zzIFTplJcvZYKA.B8/clHPZn2Ey
  3.   # encrypted of kataras_pass
  4.   role: admin
  5. - username: makis
  6.   password: $2a$10$3GXzp3J5GhHThGisbpvpZuftbmzPivDMo94XPnkTnDe7254x7sJ3O
  7.   # encrypted of makis_pass
  8.   role: member

4. Register the middleware:

  1. // Register to all matched routes
  2. // under a Party and its children.
  3. app.Use(auth)
  5. // OR/and register to all http error routes.
  6. app.UseError(auth)
  8. // OR register under a path prefix of a specific Party,
  9. // including all http errors of this path prefix.
  10. app.UseRouter(auth)
  12. // OR register to a specific Route before its main handler.
  13. app.Post("/protected", auth, routeHandler)

5. Retrieve the username & password:

  1. func routeHandler(ctx iris.Context) {
  2.     username, password, _ := ctx.Request().BasicAuth()
  3.     // [...]
  4. }

5.1 Retrieve the User value (useful when you register a slice of custom user struct at Options.AllowUsers):

  1. func routeHandler(ctx iris.Context) {
  2.     user := ctx.User().(*iris.SimpleUser)
  3.     // user.Username
  4.     // user.Password
  5. }

Read more authorization and authentication examples at _examples/auth.