github.com/germla/auth@v0.0.0-20230505173936-bc9a4159cf17/README.md (about) 1 # Auth 2 3 Auth is a modular authentication system for web development in Golang, it provides different authentication backends to accelerate your development. 4 5 Currently Auth has database password, github, google, facebook, twitter authentication support, and it is fairly easy to add other support based on [Auth's Provider interface](https://godoc.org/github.com/qor/auth#Provider) 6 7 ## Quick Start 8 9 Auth aims to provide an easy to use authentication system that don't require much developer's effort. 10 11 To use it, basic flow is: 12 13 * Initialize Auth with configuration 14 * Register some providers 15 * Register it into router 16 17 Here is an example: 18 19 ```go 20 package main 21 22 import ( 23 "github.com/qor/auth" 24 "github.com/qor/auth/auth_identity" 25 "github.com/qor/auth/providers/github" 26 "github.com/qor/auth/providers/google" 27 "github.com/qor/auth/providers/password" 28 "github.com/qor/auth/providers/facebook" 29 "github.com/qor/auth/providers/twitter" 30 "github.com/qor/session/manager" 31 32 _ "github.com/mattn/go-sqlite3" 33 34 "net/http" 35 ) 36 37 var ( 38 // Initialize gorm DB 39 gormDB, _ = gorm.Open("sqlite3", "sample.db") 40 41 // Initialize Auth with configuration 42 Auth = auth.New(&auth.Config{ 43 DB: gormDB, 44 }) 45 ) 46 47 func init() { 48 // Migrate AuthIdentity model, AuthIdentity will be used to save auth info, like username/password, oauth token, you could change that. 49 gormDB.AutoMigrate(&auth_identity.AuthIdentity{}) 50 51 // Register Auth providers 52 // Allow use username/password 53 Auth.RegisterProvider(password.New(&password.Config{})) 54 55 // Allow use Github 56 Auth.RegisterProvider(github.New(&github.Config{ 57 ClientID: "github client id", 58 ClientSecret: "github client secret", 59 })) 60 61 // Allow use Google 62 Auth.RegisterProvider(google.New(&google.Config{ 63 ClientID: "google client id", 64 ClientSecret: "google client secret", 65 AllowedDomains: []string{}, // Accept all domains, instead you can pass a whitelist of acceptable domains 66 })) 67 68 // Allow use Facebook 69 Auth.RegisterProvider(facebook.New(&facebook.Config{ 70 ClientID: "facebook client id", 71 ClientSecret: "facebook client secret", 72 })) 73 74 // Allow use Twitter 75 Auth.RegisterProvider(twitter.New(&twitter.Config{ 76 ClientID: "twitter client id", 77 ClientSecret: "twitter client secret", 78 })) 79 } 80 81 func main() { 82 mux := http.NewServeMux() 83 84 // Mount Auth to Router 85 mux.Handle("/auth/", Auth.NewServeMux()) 86 http.ListenAndServe(":9000", manager.SessionManager.Middleware(mux)) 87 } 88 ``` 89 90 That's it, then you could goto `http://127.0.0.1:9000/auth/login` to try Auth features, like login, logout, register, forgot/change password... 91 92 And it could be even easier with [Auth Themes](#auth-themes), you could integrate Auth into your application with few line configurations. 93 94 ## Usage 95 96 Auth has many configurations that could be used to customize it for different usage, lets start from Auth's [Config](http://godoc.org/github.com/qor/auth#Config). 97 98 ### Models 99 100 Auth has two models, model `AuthIdentityModel` is used to save login information, model `UserModel` is used to save user information. 101 102 The reason we save auth and user info into two different models, as we want to be able to link a user to mutliple auth info records, so a user could have multiple ways to login. 103 104 If this is not required for you, you could just set those two models to same one or skip set `UserModel`. 105 106 * `AuthIdentityModel` 107 108 Different provider usually use different information to login, like provider `password` use username/password, `github` use github user ID, so for each provider, it will save those information into its own record. 109 110 You are not necessary to set `AuthIdentityModel`, Auth has a default [definition of AuthIdentityModel](http://godoc.org/github.com/qor/auth/auth_identity#AuthIdentity), in case of you want to change it, make sure you have [auth_identity.Basic](http://godoc.org/github.com/qor/auth/auth_identity#Basic) embedded, as `Auth` assume you have same data structure in your database, so it could query/create records with SQL. 111 112 * `UserModel` 113 114 By default, there is no `UserModel` defined, even though, you still be able to use `Auth` features, `Auth` will return used auth info record as logged user. 115 116 But usually your application will have a `User` model, after you set its value, when you register a new account from any provider, Auth will create/get a user with `UserStorer`, and link its ID to the auth identity record. 117 118 ### Customize views 119 120 Auth using [Render](http://github.com/qor/render) to render pages, you could refer it for how to register func maps, extend views paths, also be sure to refer [BindataFS](https://github.com/qor/bindatafs) if you want to compile your application into a binary. 121 122 If you want to preprend view paths, you could add them to `ViewPaths`, which would be helpful if you want to overwrite the default (ugly) login/register pages or develop auth themes like [https://github.com/qor/auth_themes](https://github.com/qor/auth_themes) 123 124 ### Sending Emails 125 126 Auth using [Mailer](http://github.com/qor/mailer) to send emails, by default, Auth will print emails to console, please configure it to send real one. 127 128 ### User Storer 129 130 Auth created a default UserStorer to get/save user based on your `AuthIdentityModel`, `UserModel`'s definition, in case of you want to change it, you could implement your own [User Storer](http://godoc.org/github.com/qor/auth#UserStorerInterface) 131 132 ### Session Storer 133 134 Auth also has a default way to handle sessions, flash messages, which could be overwrited by implementing [Session Storer Interface](http://godoc.org/github.com/qor/auth#SessionStorerInterface). 135 136 By default, Auth is using [session](https://github.com/qor/session)'s default manager to save data into cookies, but in order to save cookies correctly, you have to register session's Middleware into your router, e.g: 137 138 ```go 139 func main() { 140 mux := http.NewServeMux() 141 142 // Register Router 143 mux.Handle("/auth/", Auth.NewServeMux()) 144 http.ListenAndServe(":9000", manager.SessionManager.Middleware(mux)) 145 } 146 ``` 147 148 ### Redirector 149 150 After some Auth actions, like logged, registered or confirmed, Auth will redirect user to some URL, you could configure which page to redirect with `Redirector`, by default, will redirct to home page. 151 152 If you want to redirect to last visited page, [redirect_back](https://github.com/qor/redirect_back) is for you, you could configure it and use it as the Redirector, like: 153 154 ```go 155 var RedirectBack = redirect_back.New(&redirect_back.Config{ 156 SessionManager: manager.SessionManager, 157 IgnoredPrefixes: []string{"/auth"}, 158 } 159 160 var Auth = auth.New(&auth.Config{ 161 ... 162 Redirector: auth.Redirector{RedirectBack}, 163 }) 164 ``` 165 166 BTW, to make it works correctly, `redirect_back` need to save last visisted URL into session with session manager for each request, that's means, you need to mount `redirect_back`, and `SessionManager`'s middleware into router. 167 168 ```go 169 http.ListenAndServe(":9000", manager.SessionManager.Middleware(RedirectBack.Middleware(mux))) 170 ``` 171 172 ## Advanced Usage 173 174 ### Auth Themes 175 176 In order to save more developer's effort, we have created some [auth themes](https://github.com/qor/auth_themes). 177 178 It usually has well designed pages, if you don't much custom requirements, you could just have few lines to make Auth system ready to use for your application, for example: 179 180 ```go 181 import "github.com/qor/auth_themes/clean" 182 183 var Auth = clean.New(&auth.Config{ 184 DB: db.DB, 185 Render: config.View, 186 Mailer: config.Mailer, 187 UserModel: models.User{}, 188 }) 189 ``` 190 191 Check Auth Theme's [document](https://github.com/qor/auth_themes) for How To use/create Auth themes 192 193 ### Authorization 194 195 `Authentication` is the process of verifying who you are, `Authorization` is the process of verifying that you have access to something. 196 197 Auth package not only provides `Authentication`, but also `Authorization`, please checkout [authority](https://github.com/qor/auth/tree/master/authority) for more details