{"id":13408549,"url":"https://github.com/volatiletech/authboss","last_synced_at":"2025-05-14T07:08:09.284Z","repository":{"id":25308996,"uuid":"28735637","full_name":"volatiletech/authboss","owner":"volatiletech","description":"The boss of http auth.","archived":false,"fork":false,"pushed_at":"2024-07-24T10:49:02.000Z","size":1106,"stargazers_count":3934,"open_issues_count":41,"forks_count":211,"subscribers_count":58,"default_branch":"master","last_synced_at":"2025-04-09T02:16:24.381Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/volatiletech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-03T05:12:02.000Z","updated_at":"2025-04-06T13:56:29.000Z","dependencies_parsed_at":"2023-11-19T19:24:20.621Z","dependency_job_id":"ce123efc-d11e-4672-a400-12ae05675f3c","html_url":"https://github.com/volatiletech/authboss","commit_stats":{"total_commits":493,"total_committers":34,"mean_commits":14.5,"dds":"0.37119675456389456","last_synced_commit":"0ab40e48437ad4b4284818880abe701860e98d60"},"previous_names":["go-authboss/authboss"],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volatiletech%2Fauthboss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volatiletech%2Fauthboss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volatiletech%2Fauthboss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volatiletech%2Fauthboss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/volatiletech","download_url":"https://codeload.github.com/volatiletech/authboss/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092655,"owners_count":22013290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T20:00:53.569Z","updated_at":"2025-05-14T07:08:09.259Z","avatar_url":"https://github.com/volatiletech.png","language":"Go","readme":"\u003cimg src=\"http://i.imgur.com/fPIgqLg.jpg\"/\u003e\n\n# Authboss\n\n[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4)](https://pkg.go.dev/mod/github.com/volatiletech/authboss/v3)\n![ActionsCI](https://github.com/volatiletech/authboss/workflows/test/badge.svg)\n[![Mail](https://img.shields.io/badge/mail%20list-authboss-lightgrey.svg)](https://groups.google.com/a/volatile.tech/forum/#!forum/authboss)\n![Go Coverage](https://img.shields.io/badge/coverage-84.9%25-brightgreen.svg?longCache=true\u0026style=flat)\n[![Go Report Card](https://goreportcard.com/badge/github.com/volatiletech/authboss)](https://goreportcard.com/report/github.com/volatiletech/authboss)\n\nAuthboss is a modular authentication system for the web.\n\nIt has several modules that represent authentication and authorization features that are common\nto websites in general so that you can enable as many as you need, and leave the others out.\nIt makes it easy to plug in authentication to an application and get a lot of functionality\nfor (hopefully) a smaller amount of integration effort.\n\n# New to v2?\n\nv1 -\u003e v2 was a very big change. If you're looking to upgrade there is a general guide in\n[tov2.md](tov2.md) in this project.\n\n# New to v3?\n\nv2 -\u003e v3 was not a big change, it simply changed the project to use Go modules.\nAuthboss no longer supports GOPATH as of version 3\n\n# Why use Authboss?\n\nEvery time you'd like to start a new web project, you really want to get to the heart of what you're\ntrying to accomplish very quickly and it would be a sure bet to say one of the systems you're excited\nabout implementing and innovating on is not authentication. In fact it's very much the opposite: it's\none of those things that you have to do and one of those things you loathe to do. Authboss is supposed\nto remove a lot of the tedium that comes with this, as well as a lot of the chances to make mistakes.\nThis allows you to care about what you're intending to do, rather than care about ancillary support\nsystems required to make what you're intending to do happen.\n\nHere are a few bullet point reasons you might like to try it out:\n\n* Saves you time (Authboss integration time should be less than re-implementation time)\n* Saves you mistakes (at least using Authboss, people can bug fix as a collective and all benefit)\n* Should integrate with or without any web framework\n\n# [Click Here To Get Started](https://volatiletech.github.io/authboss/#/migration)\n\n# Readme Table of Contents\n\u003c!-- TOC --\u003e\n\n- [Authboss](#authboss)\n- [New to v2?](#new-to-v2)\n- [New to v3?](#new-to-v3)\n- [Why use Authboss?](#why-use-authboss)\n- [Readme Table of Contents](#readme-table-of-contents)\n- [Getting Started](#getting-started)\n    - [App Requirements](#app-requirements)\n        - [CSRF Protection](#csrf-protection)\n        - [Request Throttling](#request-throttling)\n    - [Integration Requirements](#integration-requirements)\n        - [Middleware](#middleware)\n        - [Configuration](#configuration)\n        - [Storage and Core implementations](#storage-and-core-implementations)\n        - [ServerStorer implementation](#serverstorer-implementation)\n        - [User implementation](#user-implementation)\n        - [Values implementation](#values-implementation)\n    - [Config](#config)\n        - [Paths](#paths)\n        - [Modules](#modules)\n        - [Mail](#mail)\n        - [Storage](#storage)\n        - [Core](#core)\n- [Available Modules](#available-modules)\n- [Middlewares](#middlewares)\n- [Use Cases](#use-cases)\n    - [Get Current User](#get-current-user)\n    - [Reset Password](#reset-password)\n    - [User Auth via Password](#user-auth-via-password)\n    - [User Auth via OAuth1](#user-auth-via-oauth1)\n    - [User Auth via OAuth2](#user-auth-via-oauth2)\n    - [User Registration](#user-registration)\n    - [Confirming Registrations](#confirming-registrations)\n    - [Password Recovery](#password-recovery)\n    - [Remember Me](#remember-me)\n    - [Locking Users](#locking-users)\n    - [Expiring User Sessions](#expiring-user-sessions)\n    - [One Time Passwords](#one-time-passwords)\n    - [Two Factor Authentication](#two-factor-authentication)\n        - [Two-Factor Recovery](#two-factor-recovery)\n        - [Two-Factor Setup E-mail Authorization](#two-factor-setup-e-mail-authorization)\n        - [Time-Based One Time Passwords 2FA (totp)](#time-based-one-time-passwords-2fa-totp)\n            - [Adding 2fa to a user](#adding-2fa-to-a-user)\n            - [Removing 2fa from a user](#removing-2fa-from-a-user)\n            - [Logging in with 2fa](#logging-in-with-2fa)\n            - [Using Recovery Codes](#using-recovery-codes)\n        - [Text Message 2FA (sms)](#text-message-2fa-sms)\n            - [Adding 2fa to a user](#adding-2fa-to-a-user-1)\n            - [Removing 2fa from a user](#removing-2fa-from-a-user-1)\n            - [Logging in with 2fa](#logging-in-with-2fa-1)\n            - [Using Recovery Codes](#using-recovery-codes-1)\n    - [Rendering Views](#rendering-views)\n        - [HTML Views](#html-views)\n        - [JSON Views](#json-views)\n        - [Data](#data)\n\n\u003c!-- /TOC --\u003e\n\n# Getting Started\n\nTo get started with Authboss in the simplest way, is to simply create a Config, populate it\nwith the things that are required, and start implementing [use cases](#use-cases). The use\ncases describe what's required to be able to use a particular piece of functionality,\nor the best practice when implementing a piece of functionality. Please note the\n[app requirements](#app-requirements) for your application as well\n[integration requirements](#integration-requirements) that follow.\n\nOf course the standard practice of fetching the library is just the beginning:\n\n```bash\n# Get the latest, you must be using Go modules as of v3 of Authboss.\ngo get -u github.com/volatiletech/authboss/v3\n```\n\nHere's a bit of starter code that was stolen from the sample.\n\n```go\nab := authboss.New()\n\nab.Config.Storage.Server = myDatabaseImplementation\nab.Config.Storage.SessionState = mySessionImplementation\nab.Config.Storage.CookieState = myCookieImplementation\n\nab.Config.Paths.Mount = \"/authboss\"\nab.Config.Paths.RootURL = \"https://www.example.com/\"\n\n// This is using the renderer from: github.com/volatiletech/authboss\nab.Config.Core.ViewRenderer = abrenderer.NewHTML(\"/auth\", \"ab_views\")\n// Probably want a MailRenderer here too.\n\n\n// This instantiates and uses every default implementation\n// in the Config.Core area that exist in the defaults package.\n// Just a convenient helper if you don't want to do anything fancy.\n defaults.SetCore(\u0026ab.Config, false, false)\n\nif err := ab.Init(); err != nil {\n    panic(err)\n}\n\n// Mount the router to a path (this should be the same as the Mount path above)\n// mux in this example is a chi router, but it could be anything that can route to\n// the Core.Router.\nmux.Mount(\"/authboss\", http.StripPrefix(\"/authboss\", ab.Config.Core.Router))\n```\n\nFor a more in-depth look you **definitely should** look at the authboss sample to see what a full \nimplementation looks like. This will probably help you more than any of this documentation.\n\n[https://github.com/volatiletech/authboss-sample](https://github.com/volatiletech/authboss-sample)\n\n## App Requirements\n\nAuthboss does a lot of things, but it doesn't do some of the important things that are required by\na typical authentication system, because it can't guarantee that you're doing many of those things\nin a different way already, so it punts the responsibility.\n\n### CSRF Protection\n\nWhat this means is you should apply a middleware that can protect the application from csrf\nattacks or you may be vulnerable. Authboss previously handled this but it took on a dependency\nthat was unnecessary and it complicated the code. Because Authboss does not render views nor\nconsumes data directly from the user, it no longer does this.\n\n### Request Throttling\n\nCurrently Authboss is vulnerable to brute force attacks because there are no protections on\nit's endpoints. This again is left up to the creator of the website to protect the whole website\nat once (as well as Authboss) from these sorts of attacks.\n\n## Integration Requirements\n\nIn terms of integrating Authboss into your app, the following things must be considered.\n\n### Middleware\n\nThere are middlewares that are required to be installed in your middleware stack if it's\nall to function properly, please see [Middlewares](#middlewares) for more information.\n\n### Configuration\n\nThere are some required configuration variables that have no sane defaults and are particular\nto your app:\n\n* Config.Paths.Mount\n* Config.Paths.RootURL\n\n### Storage and Core implementations\n\nEverything under Config.Storage and Config.Core are required and you must provide them,\nhowever you can optionally use default implementations from the\n[defaults package](https://github.com/volatiletech/authboss/tree/master/defaults).\nThis also provides an easy way to share implementations of certain stack pieces (like HTML Form Parsing).\nAs you saw in the example above these can be easily initialized with the `SetCore` method in that\npackage.\n\nThe following is a list of storage interfaces, they must be provided by the implementer. Server is a\nvery involved implementation, please see the additional documentation below for more details.\n\n* Config.Storage.Server\n* Config.Storage.SessionState\n* Config.Storage.CookieState (only for \"remember me\" functionality)\n\nThe following is a list of the core pieces, these typically are abstracting the HTTP stack.\nOut of all of these you'll probably be mostly okay with the default implementations in the\ndefaults package but there are two big exceptions to this rule and that's the ViewRenderer\nand the MailRenderer. For more information please see the use case [Rendering Views](#rendering-views)\n\n* Config.Core.Router\n* Config.Core.ErrorHandler\n* Config.Core.Responder\n* Config.Core.Redirector\n* Config.Core.BodyReader\n* Config.Core.ViewRenderer\n* Config.Core.MailRenderer\n* Config.Core.Mailer\n* Config.Core.Logger\n\n### ServerStorer implementation\n\nThe [ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ServerStorer) is\nmeant to be upgraded to add capabilities depending on what modules you'd like to use.\nIt starts out by only knowing how to save and load users, but the `remember` module as an example\nneeds to be able to find users by remember me tokens, so it upgrades to a\n[RememberingServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#RememberingServerStorer)\nwhich adds these abilities.\n\nYour `ServerStorer` implementation does not need to implement all these additional interfaces\nunless you're using a module that requires it. See the [Use Cases](#use-cases) documentation to know what the requirements are.\n\n### User implementation\n\nUsers in Authboss are represented by the\n[User interface](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#User). The user\ninterface is a flexible notion, because it can be upgraded to suit the needs of the various modules.\n\nInitially the User must only be able to Get/Set a `PID` or primary identifier. This allows the authboss\nmodules to know how to refer to him in the database. The `ServerStorer` also makes use of this\nto save/load users.\n\nAs mentioned, it can be upgraded, for example suppose now we want to use the `confirm` module,\nin that case the e-mail address now becomes a requirement. So the `confirm` module will attempt\nto upgrade the user (and panic if it fails) to a\n[ConfirmableUser](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ConfirmableUser)\nwhich supports retrieving and setting of confirm tokens, e-mail addresses, and a confirmed state.\n\nYour `User` implementation does not need to implement all these additional user interfaces unless you're\nusing a module that requires it. See the [Use Cases](#use-cases) documentation to know what the\nrequirements are.\n\n### Values implementation\n\nThe [BodyReader](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#BodyReader)\ninterface in the Config returns\n[Validator](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Validator) implementations\nwhich can be validated. But much like the storer and user it can be upgraded to add different\ncapabilities.\n\nA typical `BodyReader` (like the one in the defaults package) implementation checks the page being\nrequested and switches on that to parse the body in whatever way\n(msgpack, json, url-encoded, doesn't matter), and produce a struct that has the ability to\n`Validate()` it's data as well as functions to retrieve the data necessary for the particular\nvaluer required by the module.\n\nAn example of an upgraded `Valuer` is the\n[UserValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#UserValuer)\nwhich stores and validates the PID and Password that a user has provided for the modules to use.\n\nYour body reader implementation does not need to implement all valuer types unless you're\nusing a module that requires it. See the [Use Cases](#use-cases) documentation to know what the\nrequirements are.\n\n## Config\n\nThe config struct is an important part of Authboss. It's the key to making Authboss do what you\nwant with the implementations you want. Please look at it's code definition as you read the\ndocumentation below, it will make much more sense.\n\n[Config Struct Documentation](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Config)\n\n### Paths\n\nPaths are the paths that should be redirected to or used in whatever circumstance they describe.\nTwo special paths that are required are `Mount` and `RootURL` without which certain authboss\nmodules will not function correctly. Most paths get defaulted to `/` such as after login success\nor when a user is locked out of their account.\n\n### Modules\n\nModules are module specific configuration options. They mostly control the behavior of modules.\nFor example `RegisterPreserveFields` decides a whitelist of fields to allow back into the data\nto be re-rendered so the user doesn't have to type them in again.\n\n### Mail\n\nMail sending related options.\n\n### Storage\n\nThese are the implementations of how storage on the server and the client are done in your\napp. There are no default implementations for these at this time. See the [Godoc](https://pkg.go.dev/mod/github.com/volatiletech/authboss/v3) for more information\nabout what these are.\n\n### Core\n\nThese are the implementations of the HTTP stack for your app. How do responses render? How are\nthey redirected? How are errors handled?\n\nFor most of these there are default implementations from the\n[defaults package](https://github.com/volatiletech/authboss/tree/master/defaults) available, but not for all.\nSee the package documentation for more information about what's available.\n\n# Available Modules\n\nEach module can be turned on simply by importing it and the side-effects take care of the rest.\nNot all the capabilities of authboss are represented by a module, see [Use Cases](#use-cases)\nto view the supported use cases as well as how to use them in your app.\n\n**Note**: The two factor packages do not enable via side-effect import, see their documentation\nfor more information.\n\nName      | Import Path                               | Description\n----------|-------------------------------------------|------------\nAuth      | github.com/volatiletech/authboss/v3/auth     | Database password authentication for users.\nConfirm   | github.com/volatiletech/authboss/v3/confirm  | Prevents login before e-mail verification.\nExpire    | github.com/volatiletech/authboss/v3/expire   | Expires a user's login\nLock      | github.com/volatiletech/authboss/v3/lock     | Locks user accounts after authentication failures.\nLogout    | github.com/volatiletech/authboss/v3/logout   | Destroys user sessions for auth/oauth2.\nOAuth1    | github.com/stephenafamo/authboss-oauth1      | Provides oauth1 authentication for users.\nOAuth2    | github.com/volatiletech/authboss/v3/oauth2   | Provides oauth2 authentication for users.\nRecover   | github.com/volatiletech/authboss/v3/recover  | Allows for password resets via e-mail.\nRegister  | github.com/volatiletech/authboss/v3/register | User-initiated account creation.\nRemember  | github.com/volatiletech/authboss/v3/remember | Persisting login sessions past session cookie expiry.\nOTP       | github.com/volatiletech/authboss/v3/otp      | One time passwords for use instead of passwords.\nTwofactor | github.com/volatiletech/authboss/v3/otp/twofactor | Regenerate recovery codes for 2fa.\nTotp2fa   | github.com/volatiletech/authboss/v3/otp/twofactor/totp2fa | Use Google authenticator-like things for a second auth factor.\nSms2fa    | github.com/volatiletech/authboss/v3/otp/twofactor/sms2fa | Use a phone for a second auth factor.\n\n# Middlewares\n\nThe only middleware that's truly required is the `LoadClientStateMiddleware`, and that's because it\nenables session and cookie handling for Authboss. Without that, it's not a very useful piece of\nsoftware.\n\nThe remaining middlewares are either the implementation of an entire module (like expire),\nor a key part of a module. For example you probably wouldn't want to use the lock module\nwithout the middleware that would stop a locked user from using an authenticated resource,\nbecause then locking wouldn't be useful unless of course you had your own way of dealing\nwith locking, which is why it's only recommended, and not required. Typically you will\nuse the middlewares if you use the module.\n\nName | Requirement | Description\n---- | ----------- | -----------\n[Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Middleware) | Recommended | Prevents unauthenticated users from accessing routes.\n[LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware) | **Required** | Enables cookie and session handling\n[ModuleListMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.ModuleListMiddleware) | Optional | Inserts a loaded module list into the view data\n[confirm.Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/confirm/#Middleware) | Recommended with confirm | Ensures users are confirmed or rejects request\n[expire.Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/expire/#Middleware) | **Required** with expire | Expires user sessions after an inactive period\n[lock.Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/lock/#Middleware) | Recommended with lock | Rejects requests from locked users\n[remember.Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/remember/#Middleware) | Recommended with remember | Logs a user in from a remember cookie\n\n\n# Use Cases\n\n## Get Current User\n\nCurrentUser can be retrieved by calling\n[Authboss.CurrentUser](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.CurrentUser)\nbut a pre-requisite is that\n[Authboss.LoadClientState](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientState)\nhas been called first to load the client state into the request context.\nThis is typically achieved by using the\n[Authboss.LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware), but can\nbe done manually as well.\n\n## Reset Password\n\nUpdating a user's password is non-trivial for several reasons:\n\n1. The bcrypt algorithm must have the correct cost, and also be being used.\n1. The user's remember me tokens should all be deleted so that previously authenticated sessions are invalid\n1. Optionally the user should be logged out (**not taken care of by UpdatePassword**)\n\nIn order to do this, we can use the\n[Authboss.UpdatePassword](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.UpdatePassword)\nmethod. This ensures the above facets are taken care of which the exception of the logging out part.\n\nIf it's also desirable to have the user logged out, please use the following methods to erase\nall known sessions and cookies from the user.\n\n* [authboss.DelKnownSession](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#DelKnownSession)\n* [authboss.DelKnownCookie](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#DelKnownCookie)\n\n*Note: DelKnownSession has been deprecated for security reasons*\n\n## User Auth via Password\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | auth\nPages         | login\nRoutes        | /login\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session and Cookie\nServerStorer  | [ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ServerStorer)\nUser          | [AuthableUser](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#AuthableUser)\nValues        | [UserValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#UserValuer)\nMailer        | _None_\n\nTo enable this side-effect import the auth module, and ensure that the requirements above are met.\nIt's very likely that you'd also want to enable the logout module in addition to this.\n\nDirect a user to `GET /login` to have them enter their credentials and log in.\n\n## User Auth via OAuth1\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | oauth1\nPages         | _None_\nRoutes        | /oauth1/{provider}, /oauth1/callback/{provider}\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session\nServerStorer  | [OAuth1ServerStorer](https://pkg.go.dev/github.com/stephenafamo/authboss-oauth1?tab=doc#ServerStorer)\nUser          | [OAuth1User](https://pkg.go.dev/github.com/stephenafamo/authboss-oauth1?tab=doc#User)\nValues        | _None_\nMailer        | _None_\n\nThis is a tougher implementation than most modules because there's a lot going on. In addition to the\nrequirements stated above, you must also configure the `oauth1.Providers`. It's a public variable in the module.\n\n```go\nimport oauth1 \"github.com/stephenafamo/authboss-oauth1\"\n\noauth1.Providers = map[string]oauth1.Provider{}\n```\n\nThe providers require an oauth1 configuration that's typical for the Go oauth1 package, but in addition\nto that they need a `FindUserDetails` method which has to take the token that's retrieved from the oauth1\nprovider, and call an endpoint that retrieves details about the user (at LEAST user's uid).\nThese parameters are returned in `map[string]string` form and passed into the `oauth1.ServerStorer`.\n\nPlease see the following documentation for more details:\n\n* [Package docs for oauth1](https://pkg.go.dev/github.com/stephenafamo/authboss-oauth1)\n* [oauth1.Provider](https://pkg.go.dev/github.com/stephenafamo/authboss-oauth1?tab=doc#Provider)\n* [oauth1.ServerStorer](https://pkg.go.dev/github.com/stephenafamo/authboss-oauth1/#OAuth1ServerStorer)\n\n## User Auth via OAuth2\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | oauth2\nPages         | _None_\nRoutes        | /oauth2/{provider}, /oauth2/callback/{provider}\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session\nServerStorer  | [OAuth2ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#OAuth2ServerStorer)\nUser          | [OAuth2User](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#OAuth2User)\nValues        | _None_\nMailer        | _None_\n\nThis is a tougher implementation than most modules because there's a lot going on. In addition to the\nrequirements stated above, you must also configure the `OAuth2Providers` in the config struct.\n\nThe providers require an oauth2 configuration that's typical for the Go oauth2 package, but in addition\nto that they need a `FindUserDetails` method which has to take the token that's retrieved from the oauth2\nprovider, and call an endpoint that retrieves details about the user (at LEAST user's uid).\nThese parameters are returned in `map[string]string` form and passed into the `OAuth2ServerStorer`.\n\nPlease see the following documentation for more details:\n\n* [Package docs for oauth2](https://pkg.go.dev/github.com/volatiletech/authboss/v3/oauth2/)\n* [authboss.OAuth2Provider](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#OAuth2Provider)\n* [authboss.OAuth2ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#OAuth2ServerStorer)\n\n## User Registration\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | register\nPages         | register\nRoutes        | /register\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session\nServerStorer  | [CreatingServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#CreatingServerStorer)\nUser          | [AuthableUser](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#AuthableUser), optionally [ArbitraryUser](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ArbitraryUser)\nValues        | [UserValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#UserValuer), optionally also [ArbitraryValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ArbitraryValuer)\nMailer        | _None_\n\nUsers can self-register for a service using this module. You may optionally want them to confirm\nthemselves, which can be done using the confirm module.\n\nThe complicated part in implementing registrations are around the `RegisterPreserveFields`. This is to\nhelp in the case where a user fills out many fields, and then say enters a password\nwhich doesn't meet minimum requirements and it fails during validation. These preserve fields should\nstop the user from having to type in all that data again (it's a whitelist). This **must** be used\nin conjuction with `ArbitraryValuer` and although it's not a hard requirement `ArbitraryUser`\nshould be used otherwise the arbitrary values cannot be stored in the database.\n\nWhen the register module sees arbitrary data from an `ArbitraryValuer`, it sets the data key\n`authboss.DataPreserve` with a `map[string]string` in the data for when registration fails.\nThis means the (whitelisted) values entered by the user previously will be accessible in the\ntemplates by using `.preserve.field_name`. Preserve may be empty or nil so use\n`{{with ...}}` to make sure you don't have template errors.\n\nThere is additional [Godoc documentation](https://pkg.go.dev/mod/github.com/volatiletech/authboss/v3#Config) on the `RegisterPreserveFields` config option as well as\nthe `ArbitraryUser` and `ArbitraryValuer` interfaces themselves.\n\n## Confirming Registrations\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | confirm\nPages         | confirm\nRoutes        | /confirm\nEmails        | confirm_html, confirm_txt\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware), [confirm.Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/confirm/#Middleware)\nClientStorage | Session\nServerStorer  | [ConfirmingServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ConfirmingServerStorer)\nUser          | [ConfirmableUser](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ConfirmableUser)\nValues        | [ConfirmValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ConfirmValuer)\nMailer        | Required\n\nConfirming registrations via e-mail can be done with this module (whether or not done via the register\nmodule).\n\nA hook on register kicks off the start of a confirmation which sends an e-mail with a token for the user.\nWhen the user re-visits the page, the `BodyReader` must read the token and return a type that returns\nthe token.\n\nConfirmations carry two values in the database to prevent a timing attack. The selector and the\nverifier, always make sure in the ConfirmingServerStorer you're searching by the selector and\nnot the verifier.\n\n## Password Recovery\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | recover\nPages         | recover_start, recover_middle (not used for renders, only values), recover_end\nRoutes        | /recover, /recover/end\nEmails        | recover_html, recover_txt\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session\nServerStorer  | [RecoveringServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#RecoveringServerStorer)\nUser          | [RecoverableUser](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#RecoverableUser)\nValues        | [RecoverStartValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#RecoverStartValuer), [RecoverMiddleValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#RecoverMiddleValuer), [RecoverEndValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#RecoverEndValuer)\nMailer        | Required\n\nThe flow for password recovery is that the user is initially shown a page that wants their `PID` to\nbe entered. The `RecoverStartValuer` retrieves that on `POST` to `/recover`.\n\nAn e-mail is sent out, and the user clicks the link inside it and is taken back to `/recover/end`\nas a `GET`, at this point the `RecoverMiddleValuer` grabs the token and will insert it into the data\nto be rendered.\n\nThey enter their password into the form, and `POST` to `/recover/end` which sends the token and\nthe new password which is retrieved by `RecoverEndValuer` which sets their password and saves them.\n\nPassword recovery has two values in the database to prevent a timing attack. The selector and the\nverifier, always make sure in the RecoveringServerStorer you're searching by the selector and\nnot the verifier.\n\n## Remember Me\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | remember\nPages         | _None_\nRoutes        | _None_\nEmails        | _None_\nMiddlewares   | LoadClientStateMiddleware,\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware), [remember.Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/remember/#Middleware)\nClientStorage | Session, Cookies\nServerStorer  | [RememberingServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#RememberingServerStorer)\nUser          | User\nValues        | [RememberValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#RememberValuer) (not a Validator)\nMailer        | _None_\n\nRemember uses cookie storage to log in users without a session via the `remember.Middleware`.\nBecause of this this middleware should be used high up in the stack, but it also needs to be after\nthe `LoadClientStateMiddleware` so that client state is available via the authboss mechanisms.\n\nThere is an intricacy to the `RememberingServerStorer`, it doesn't use the `User` struct at all,\ninstead it simply instructs the storer to save tokens to a pid and recall them just the same. Typically\nin most databases this will require a separate table, though you could implement using pg arrays\nor something as well.\n\nA user who is logged in via Remember tokens is also considered \"half-authed\" which is a session\nkey (`authboss.SessionHalfAuthKey`) that you can query to check to see if a user should have\nfull rights to more sensitive data, if they are half-authed and they want to change their user\ndetails for example you may want to force them to go to the login screen and put in their\npassword to get a full auth first. The `authboss.Middleware` has a boolean flag to `forceFullAuth`\nwhich prevents half-authed users from using that route.\n\n## Locking Users\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | lock\nPages         | _None_\nRoutes        | _None_\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware), [lock.Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/lock/#Middleware)\nClientStorage | Session\nServerStorer  | [ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ServerStorer)\nUser          | [LockableUser](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#LockableUser)\nValues        | _None_\nMailer        | _None_\n\nLock ensures that a user's account becomes locked if authentication (both auth, oauth2, otp) are\nfailed enough times.\n\nThe middleware protects resources from locked users, without it, there is no point to this module.\nYou should put in front of any resource that requires a login to function.\n\n## Expiring User Sessions\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | expire\nPages         | _None_\nRoutes        | _None_\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware), [expire.Middleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/expire/#Middleware)\nClientStorage | Session\nServerStorer  | _None_\nUser          | [User](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#User)\nValues        | _None_\nMailer        | _None_\n\n**Note:** Unlike most modules in Authboss you must call `expire.Setup()`\nto enable this module. See the sample to see how to do this. This may be changed in the future.\n\nExpire simply uses sessions to track when the last action of a user is, if that action is longer\nthan configured then the session is deleted and the user removed from the request context.\n\nThis middleware should be inserted at a high level (closer to the request) in the middleware chain\nto ensure that \"activity\" is logged properly, as well as any middlewares down the chain do not\nattempt to do anything with the user before it's removed from the request context.\n\n## One Time Passwords\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | otp\nPages         | otp, otpadd, otpclear\nRoutes        | /otp/login, /otp/add, /otp/clear\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session and Cookie\nServerStorer  | [ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ServerStorer)\nUser          | [otp.User](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/#User)\nValues        | [UserValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#UserValuer)\nMailer        | _None_\n\nOne time passwords can be useful if users require a backup password in case they lose theirs,\nor they're logging in on an untrusted computer. This module allows users to add one time passwords,\nclear them, or log in with them.\n\nLogging in with a one time password instead of a password is identical to having logged in normally\nwith their typical password with the exception that the one time passwords are consumed immediately\nupon use and cannot be used again.\n\n`otp` should not be confused with two factor authentication. Although 2fa also uses one-time passwords\nthe `otp` module has nothing to do with it and is strictly a mechanism for logging in with an alternative\nto a user's regular password.\n\n## Two Factor Authentication\n\n2FA in Authboss is implemented in a few separate modules: twofactor, totp2fa and sms2fa.\n\nYou should use two factor authentication in your application if you want additional security beyond\nthat of just simple passwords. Each 2fa module supports a different mechanism for verifying a second\nfactor of authentication from a user.\n\n### Two-Factor Recovery\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | twofactor\nPages         | recovery2fa\nRoutes        | /2fa/recovery/regen\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session\nServerStorer  | [ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ServerStorer)\nUser          | [twofactor.User](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/#User)\nValues        | _None_\nMailer        | _None_\n\n**Note:** Unlike most modules in Authboss you must construct a `twofactor.Recovery` and call `.Setup()`\non it to enable this module. See the sample to see how to do this. This may be changed in the future.\n\nPackage twofactor is all about the common functionality of providing backup codes for two factor\nmechanisms. Instead of each module implementing backup codes on it's own, common functionality has\nbeen put here including a route to regenerate backup codes.\n\nBackup codes are useful in case people lose access to their second factor for authentication. This happens\nwhen users lose their phones for example. When this occurs, they can use one of their backup-codes.\n\nBackup codes are one-time use, they are bcrypted for security, and they only allow bypassing the 2fa\nauthentication part, they cannot be used in lieu of a user's password, for that sort of recovery see\nthe `otp` module.\n\n### Two-Factor Setup E-mail Authorization\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | twofactor\nPages         | twofactor_verify\nRoutes        | /2fa/recovery/regen\nEmails        | twofactor_verify_email_html, twofactor_verify_email_txt\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session\nServerStorer  | [ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ServerStorer)\nUser          | [twofactor.User](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/#User)\nValues        | [twofactor.EmailVerifyTokenValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/#EmailVerifyTokenValuer)\nMailer        | Required\n\nTo enable this feature simply turn on\n`authboss.Config.Modules.TwoFactorEmailAuthRequired` and new routes and\nmiddlewares will be installed when you set up one of the 2fa modules.\n\nWhen enabled, the routes for setting up 2fa on an account are protected by a\nmiddleware that will redirect to `/2fa/{totp,sms}/email/verify` where\nPage `twofactor_verify` is displayed. The user is prompted to authorize the\naddition of 2fa to their account. The data for this page contains `email` and\na `url` for the POST. The url is required because this page is shared between\nall 2fa types.\n\nOnce they POST to the url, a token is stored in their session and an e-mail is\nsent with that token. When they click the link that goes to\n`/2fa/{totp,sms}/email/verify/end` with a token in the query string the session\ntoken is verified and exchanged for a value that says they're verified and\nlastly it redirects them to the setup URL for the type of 2fa they were\nattempting to setup.\n\n### Time-Based One Time Passwords 2FA (totp)\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | totp2fa\nPages         | totp2fa_{setup,confirm,remove,validate}, totp2fa_{confirm,remove}_success\nRoutes        | /2fa/totp/{setup,confirm,qr,remove,validate}\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session **(SECURE!)**\nServerStorer  | [ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ServerStorer)\nUser          | [totp2fa.User](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/totp2fa/#User)\nValues        | [TOTPCodeValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/totp2fa/#TOTPCodeValuer)\nMailer        | _None_\n\n**Note:** Unlike most modules in Authboss you must construct a `totp2fa.TOTP` and call `.Setup()`\non it to enable this module. See the sample to see how to do this This may be changed in the future.\n\n**Note:** To allow users to regenerate their backup codes, you must also use the `twofactor` module.\n\n**Note:** Routes are protected by `authboss.Middleware` so only logged in users can access them.\nYou can configure whether unauthenticated users should be redirected to log in or are 404'd using\nthe `authboss.Config.Modules.RoutesRedirectOnUnathed` configuration flag.\n\n#### Adding 2fa to a user\n\nWhen a logged in user would like to add 2fa to their account direct them `GET /2fa/totp/setup`, the `GET`\non this page does virtually nothing so you don't have to use it, just `POST` immediately to have\na smoother flow for the user. **This puts the 2fa secret in their session temporarily meaning you must\nhave proper secure sessions for this to be secure.**\n\nThey will be redirected to `GET /2fa/totp/confirm` where the data will show `totp2fa.DataTOTPSecret`,\nthis is the key that user's should enter into their Google Authenticator or similar app. Once they've\nadded it they need to send a `POST /2fa/totp/confirm` with a correct code which removes the 2fa secret\nfrom their session and permanently adds it to their `totp2fa.User` and 2fa is now enabled for them.\nThe data from the `POST` will contain a key `twofactor.DataRecoveryCodes` that contains an array\nof recovery codes for the user.\n\nIf you wish to show the user a QR code, `GET /2fa/totp/qr` at any time during or after totp2fa setup\nwill return a 200x200 png QR code that they can scan.\n\n#### Removing 2fa from a user\n\nA user begins by going to `GET /2fa/totp/remove` and enters a code which posts to `POST /2fa/totp/remove`\nand if it's correct they're shown a success page and 2fa is removed from them, if not they get\nvalidation errors.\n\n#### Logging in with 2fa\n\nWhen a user goes to log in, the `totp` module checks the user after they log in for the presence of\na totp2fa secret, if there is one it does not give them a logged in session value immediately and\nredirects them to `GET /2fa/totp/validate` where they must enter a correct code to `POST /2fa/totp/validate`\nif the code is correct they're logged in normally as well as they get the session value\n`authboss.Session2FA` set to `\"totp\"` to prove that they've authenticated with two factors.\n\n#### Using Recovery Codes\n\nBoth when logging in and removing totp2fa from an account, a recovery code may be used instead. They can\n`POST` to the same url, they simply send a different form field. The recovery code is consumed on use\nand may not be used again.\n\n### Text Message 2FA (sms)\n\nPackage sms2fa uses sms shared secrets as a means to authenticate a user with a second factor:\ntheir phone number.\n\n| Info and Requirements |          |\n| --------------------- | -------- |\nModule        | sms2fa\nPages         | sms2fa_{setup,confirm,remove,validate}, sms2fa_{confirm,remove}_success\nRoutes        | /2fa/{setup,confirm,remove,validate}\nEmails        | _None_\nMiddlewares   | [LoadClientStateMiddleware](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Authboss.LoadClientStateMiddleware)\nClientStorage | Session (**SECURE!**)\nServerStorer  | [ServerStorer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#ServerStorer)\nUser          | [sms2fa.User](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/sms2fa/#User), [sms2fa.SMSNumberProvider](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/sms2fa/#SMSNumberProvider)\nValues        | [SMSValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/sms2fa/#SMSValuer), [SMSPhoneNumberValuer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/otp/twofactor/sms2fa/#SMSPhoneNumberValuer)\nMailer        | _None_\n\n**Note:** Unlike most modules in Authboss you must construct a `sms2fa.SMS` and call `.Setup()`\non it to enable this module. See the sample to see how to do this. This may be changed in the future.\n\n**Note:** To allow users to regenerate their backup codes, you must also use the `twofactor` module.\n\n**Note:** Routes are protected by `authboss.Middleware` so only logged in users can access them.\nYou can configure whether unauthenticated users should be redirected to log in or are 404'd using\nthe `authboss.Config.Modules.RoutesRedirectOnUnathed` configuration flag.\n\n**Note:** sms2fa always stores the code it's expecting in the user's session therefore **you must\nhave secure sessions or the code itself is not secure!**\n\n**Note:** sms2fa pages all send codes via sms on `POST` when no data code is given. This is also how\nusers can resend the code in case they did not get it (for example a second\n`POST /2fa/sms/{confirm,remove}` with no form-fields filled in will end up resending the code).\n\n**Note:** Sending sms codes is rate-limited to 1 sms/10 sec for that user, this is controlled by placing\na timestamp in their session to prevent abuse.\n\n#### Adding 2fa to a user\n\nWhen a logged in user would like to add 2fa to their account direct them `GET /2fa/sms/setup` where\nthey must enter a phone number. If the logged in user also implements `sms2fa.SMSNumberProvider` then\nthis interface will be used to retrieve a phone number (if it exists) from the user and put it in\n`sms2fa.DataSMSPhoneNumber` so that the user interface can populate it for the user, making it convenient\nto re-use an already saved phone number inside the user.\n\nOnce they `POST /2fa/sms/setup` with a phone number, the `sms2fa.Sender` interface will be\ninvoked to send the SMS code to the user and they will be redirected to `GET /2fa/sms/confirm` where\nthey enter the code they received which does a `POST /2fa/sms/confirm` to store the phone number\nthey were confirming permanently on their user using `sms2fa.User` which enables sms2fa for them.\nThe data from the `POST` will contain a key `twofactor.DataRecoveryCodes` that contains an array\nof recovery codes for the user.\n\n#### Removing 2fa from a user\n\nA user begins by going to `GET /2fa/sms/remove`. This page does nothing on it's own. In order to\nbegin the process `POST /2fa/sms/remove` with no data (or a recovery code to skip needing the sms code)\nto send the sms code to the user. Then they can `POST /2fa/sms/remove` again with the correct code\nto have it permanently removed.\n\n#### Logging in with 2fa\n\nWhen a user goes to log in, the `sms` module checks the user after they log in for the presence of\na sms2fa phone number, if there is one it does not give them a logged in session value but instead\nsends an SMS code to their configured number and and redirects them to `GET /2fa/sms/validate`\nwhere they must enter a correct code to `POST /2fa/totp/validate`. If the code is correct they're\nlogged in normally as well as they get the session value `authboss.Session2FA` set to `\"sms\"` to prove\nthat they've authenticated with two factors.\n\n#### Using Recovery Codes\n\nSame as totp2fa above.\n\n## Rendering Views\n\nThe authboss rendering system is simple. It's defined by one interface: [Renderer](https://pkg.go.dev/github.com/volatiletech/authboss/v3/#Renderer)\n\nThe renderer knows how to load templates, and how to render them with some data and that's it.\nSo let's examine the most common view types that you might want to use.\n\n### HTML Views\n\nWhen your app is a traditional web application and is generating it's HTML\nserverside using templates this becomes a small wrapper on top of your rendering\nsetup. For example if you're using `html/template` then you could just use\n`template.New()` inside the `Load()` method and store that somewhere and call\n`template.Execute()` in the `Render()` method.\n\nThere is also a very basic renderer: [Authboss\nRenderer](https://github.com/volatiletech/authboss-renderer) which has some very\nugly built in views and the ability to override them with your own if you don't\nwant to integrate your own rendering system into that interface.\n\n### JSON Views\n\nIf you're building an API that's mostly backed by a javascript front-end, then you'll probably\nwant to use a renderer that converts the data to JSON. There is a simple json renderer available in\nthe [defaults package](https://github.com/volatiletech/authboss/tree/master/defaults) package if you wish to\nuse that.\n\n### Data\n\nThe most important part about this interface is the data that you have to render.\nThere are several keys that are used throughout authboss that you'll want to render in your views.\n\nThey're in the file [html_data.go](https://github.com/volatiletech/authboss/blob/master/html_data.go)\nand are constants prefixed with `Data`. See the documentation in that file for more information on\nwhich keys exist and what they contain.\n\nThe default [responder](https://pkg.go.dev/github.com/volatiletech/authboss/v3/defaults/#Responder)\nalso happens to collect data from the Request context, and hence this is a great place to inject\ndata you'd like to render (for example data for your html layout, or csrf tokens).\n","funding_links":[],"categories":["Authentication and Authorization","Authentication and OAuth","HarmonyOS","身份验证和OAuth","开源类库","Go","Projects","Authentication","Open source library","\u003cspan id=\"身份验证和oauth-authentication-and-auth\"\u003e身份验证和OAuth Authentication and Auth\u003c/span\u003e","认证和授权","認證和授權","Uncategorized","认证和OAuth授权","认证与权限控制"],"sub_categories":["Windows Manager","Auth","Contents","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolatiletech%2Fauthboss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolatiletech%2Fauthboss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolatiletech%2Fauthboss/lists"}