github.com/rivo/users
Package users implements common web user workflows. Most of the provided functions are regular net/http handler functions. The following functionality is provided: Special emphasis is placed on reducing the risk of someone hijacking user accounts. This is achieved by enforcing a certain user structure and following certain procedures: If your application does not follow these principles, you may not be able to use this package as is. However, the code may serve as a starting point if you apply its principles to your own use case. Note also the following: The users.Main() function registers all handlers and starts an HTTP server: Any other handlers can be added to the http.DefaultServeMux before calling users.Main(). Alternatively, you can start your own HTTP server. See the implementation of users.Main() for how to add the package's handlers. See the package example for a most basic way to use the package. In addition, the global Config struct contains all the variables that need to be adjusted for your specific application. It provides sensible defaults out of the box which you can see in its documentation. The fields are as follows: The following fields control how templates are handled: If your application supports internationalization, you can set the Internationalization field to true. If set to true, this package's code checks for the "lang" cookie and appends its value to the HTMLTemplateDir and MailTemplateDir directories to search for template files. Cookie values must be of the format "xx" or "xx-XX" (e.g. "en-US"). If they don't have this format or if the corresponding subdirectory does not exist, the search falls back to the HTMLTemplateDir and MailTemplateDir directories. It is up to the application to set the "lang" cookie. Emails are sent if the SendEmails field is set to true. You can provide your own email function by implementing the SendEmail field. Alternatively, the net/smtp package is used to send emails. The following fields need to specified (fields starting with "SMTP" are only needed when you don't provide your own SendEmail implementation): A number of functions serve as the interface to your database: Anyone using this package must define a type which implements this package's User interface. A user is in one of three possible states: Users have an ID which must be unique (e.g. generated by CUID() in the package github.com/rivo/sessions). But this package may access users based on their unique email address, their verification ID, or their password reset token. You must implement the Config.NewUser function. There are basic HTML templates (in the "html" subdirectory) and email templates (in the "mail" subdirectory). All HTML templates starting with "error_" are templates that will generate error messages which are then embedded in another HTML template. When starting to work with this package, you will want to make a copy of these two subdirectories and modify the templates to your needs. This package implements some functions to render templates which are also public so you may use them in other places, too. The function RenderPage() takes a template filename and a data object (to which the template will be bound), renders the template, and sends it to the browser. Instead of calling this function, however, RenderPageBasic() is used more often. It calls RenderPage() but populates the data object with the Config object and the User object (if one was provided). If an error message needs to be shown to the user, RenderPageError() can be used. This actually involves two templates, one to generate only the error message (these template files start with "error_"), and the other to generate the HTML file which shows the error message. Config and User will also be bound to the latter as well as any data sent to the error message template. There is another function for errors, RenderProgramError(), which is used to show program errors. These are unexpected errors, for example database connection issues, and should always be followed up on. While the user usually only sees a basic error message, more detailed information about the error is sent to the logger for further inspection. The SendMail() function renders mail templates (based on text/template) to send them to the user's email address. When writing your own templates, it is helpful to make a copy of the existing example templates and modify them to your needs. All templates include a header and a footer file. If you include more files, you will need to set the Config.HTMLTemplateIncludes and Config.MailTemplateIncludes fields accordingly.
Readme
This Go package provides net/http handlers for the following functions:
Special emphasis is placed on reducing the risk of someone hijacking user accounts. This is achieved by enforcing a certain user structure and following certain procedures:
go get github.com/rivo/users
The users.Main() function registers all handlers and starts an HTTP server:
if err := users.Main(); err != nil {
panic(err)
}
Alternatively, register the handlers and start the server yourself:
http.HandleFunc(users.Config.RouteSignUp, users.SignUp)
http.HandleFunc(users.Config.RouteVerify, users.Verify)
http.HandleFunc(users.Config.RouteLogIn, users.LogIn)
http.HandleFunc(users.Config.RouteLogOut, users.LogOut)
http.HandleFunc(users.Config.RouteForgottenPassword, users.ForgottenPassword)
http.HandleFunc(users.Config.RouteResetPassword, users.ResetPassword)
http.HandleFunc(users.Config.RouteChange, users.Change)
if err := http.ListenAndServe(users.Config.ServerAddr, nil); err != nil {
panic(err)
}
If you use these handlers as they are, you will need access to an SMTP mail server (for email verification and password reset emails).
For pages behind the login, you can use the users.IsLoggedIn() function in your own handler:
user, _, _ := users.IsLoggedIn(response, request)
if user == nil {
users.RenderProgramError(response, request, "You must be logged in", "", nil)
return
}
fmt.Fprintf(response, "You are logged in: %s", user.GetEmail())
This package uses Golang HTML templates for the various pages and text templates for the various emails sent to the user. Basic templates are provided which can be customized to your needs. Internationalization is supported via the "lang" browser cookie.
The users.User type is an interface. Bring your own user model.
The users.Config struct provides a number of fields with sensible defaults but which may be customized for your application. Refer to the Godoc documentation for details.
No specific database backend is assumed. The functions to load and save users default to a RAM-based solution but can be customized to access your individual database.
See http://godoc.org/github.com/rivo/users for the documentation.
See also the https://github.com/rivo/users/wiki for more examples and explanations.
Add your issue here on GitHub. Feel free to get in touch if you have any questions.
FAQs
Package users implements common web user workflows. Most of the provided functions are regular net/http handler functions. The following functionality is provided: Special emphasis is placed on reducing the risk of someone hijacking user accounts. This is achieved by enforcing a certain user structure and following certain procedures: If your application does not follow these principles, you may not be able to use this package as is. However, the code may serve as a starting point if you apply its principles to your own use case. Note also the following: The users.Main() function registers all handlers and starts an HTTP server: Any other handlers can be added to the http.DefaultServeMux before calling users.Main(). Alternatively, you can start your own HTTP server. See the implementation of users.Main() for how to add the package's handlers. See the package example for a most basic way to use the package. In addition, the global Config struct contains all the variables that need to be adjusted for your specific application. It provides sensible defaults out of the box which you can see in its documentation. The fields are as follows: The following fields control how templates are handled: If your application supports internationalization, you can set the Internationalization field to true. If set to true, this package's code checks for the "lang" cookie and appends its value to the HTMLTemplateDir and MailTemplateDir directories to search for template files. Cookie values must be of the format "xx" or "xx-XX" (e.g. "en-US"). If they don't have this format or if the corresponding subdirectory does not exist, the search falls back to the HTMLTemplateDir and MailTemplateDir directories. It is up to the application to set the "lang" cookie. Emails are sent if the SendEmails field is set to true. You can provide your own email function by implementing the SendEmail field. Alternatively, the net/smtp package is used to send emails. The following fields need to specified (fields starting with "SMTP" are only needed when you don't provide your own SendEmail implementation): A number of functions serve as the interface to your database: Anyone using this package must define a type which implements this package's User interface. A user is in one of three possible states: Users have an ID which must be unique (e.g. generated by CUID() in the package github.com/rivo/sessions). But this package may access users based on their unique email address, their verification ID, or their password reset token. You must implement the Config.NewUser function. There are basic HTML templates (in the "html" subdirectory) and email templates (in the "mail" subdirectory). All HTML templates starting with "error_" are templates that will generate error messages which are then embedded in another HTML template. When starting to work with this package, you will want to make a copy of these two subdirectories and modify the templates to your needs. This package implements some functions to render templates which are also public so you may use them in other places, too. The function RenderPage() takes a template filename and a data object (to which the template will be bound), renders the template, and sends it to the browser. Instead of calling this function, however, RenderPageBasic() is used more often. It calls RenderPage() but populates the data object with the Config object and the User object (if one was provided). If an error message needs to be shown to the user, RenderPageError() can be used. This actually involves two templates, one to generate only the error message (these template files start with "error_"), and the other to generate the HTML file which shows the error message. Config and User will also be bound to the latter as well as any data sent to the error message template. There is another function for errors, RenderProgramError(), which is used to show program errors. These are unexpected errors, for example database connection issues, and should always be followed up on. While the user usually only sees a basic error message, more detailed information about the error is sent to the logger for further inspection. The SendMail() function renders mail templates (based on text/template) to send them to the user's email address. When writing your own templates, it is helpful to make a copy of the existing example templates and modify them to your needs. All templates include a header and a footer file. If you include more files, you will need to set the Config.HTMLTemplateIncludes and Config.MailTemplateIncludes fields accordingly.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).
Security News
LDAPjs, an LDAP Client and Server API for Node.js, was decommissioned after its maintainer received an abusive email from a user, raising concerns about this form of abuse as a potential attack vector.
Security News
CISA launched a new project called Vulnrichment to enrich CVEs with details that help prioritize patching and mitigation efforts, as the NVD backlog of unenriched CVEs awaiting analysis surpasses 10,000.