README.md
1# easyauth
2This package aims to make authentication in go apps as simple as possible. It currently supports the following authentication methods:
3
4- LDAP
5- Api Tokens
6- Oauth (soon)
7- Custom user database (soon)
8
9It provides an end-to-end solution for integrating any or all of these providers into your app, including:
10
11- Access control middleware (compatible with almost any web framework)
12- Secure session cookie management
13- Fine grained, endpoint level access control
14- All needed http handlers, callbacks, login pages, etc. generated for you
15- Full customizability
16
17## Usage
18
19### Role based access-control
20easyauth uses a role-based permission system to control access to resources. Your application can define whatever roles and access levels that are appropriate. A typical setup may look like this:
21
22```
23const(
24 //capabilities are bit flags. Content usually requires specific capabilities/
25 CanRead easyauth.Role = 1 << iota
26 CanWrite
27 CanModerate
28 CanViewSystemStats
29 CanChangeSettings
30
31 //roles combine flags. Users have an associated role value
32 RoleReader = CanRead
33 RoleWriter = RoleReader | CanWrite
34 RoleMod = RoleWriter | CanModerate
35 RoleAdmin = RoleMod | CanViewSystemStats | CanChangeSettings
36)
37```
38
39### Getting Started
40
41`import "github.com/captncraig/easyauth"`
42
431. Create a new `AuthManager`.
44
45 ```
46 auth := easyAuth.New(...)
47 ```
48 This call accepts any number of option modifiers. See [options](#options) for full options documentation.
49
502. Add Providers:
51
52 Here I will add an ldap provider:
53
54 ```
55l := &ldap.LdapProvider{
56 LdapAddr: "ad.myorg.com:3269",
57 DefaultPermission: RoleReader,
58 Domain: "MYORG",
59}
60auth.AddProvider("ldap", l)
61 ```
62
63 Anyone who enters valid credentials will be granted the "Reader" role as defined by my app's role structure.
64
65 You can add as many different providers as you wish. See [providers](#providers) for detailed info on how to use and configure indivisual providers.
66
673. Register auth handler:
68
69 ```
70http.Handle("/auth/", http.StripPrefix("/auth", auth.LoginHandler()))
71 ```
72
73 This handler will handle all requests to `/auth/*` and handle them as appropriate. This include login pages,
74callbacks, form posts, logout requests, deny pages and so forth.
75
764. Apply middeware to your app's http handlers:
77 ```
78http.Handle("/api/stats", auth.Wrap(myStatHandler,CanViewSystemStats))
79 ```
80 Each handler can specify their own requirements for user capabilities to access that content.
81
82### options
83
84- `CookieSecret("superSecretString")`: set the secret used to hash and encrypt all cookies made by the system. Can be any string, but I recommend using 64 bytes of random data, base64 encoded.
85You can generate a suitable secret with this command: `go test github.com/captncraig/easyauth -run TestGenerateKey -v`
86- `CookieDuration(int seconds)`: Set the default duration for all session cookies. Defaults to 30 days.
87- `LoginTemplate(tmpl string)`: Override the [built-in](https://github.com/captncraig/easyauth/blob/master/template.go) template for the login page. The context is a bit tricky to support multiple types of providers, but the example should serve as a decent model. If your app has a known set of providers/options, then a custom login page may be much easier.
88