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