basis/furnace/auth/auth-docs.factor

   1 USING: assocs classes help.markup help.syntax kernel
   2 quotations strings words furnace.auth.providers.db
   3 checksums.sha2 furnace.auth.providers math byte-arrays
   4 http multiline ;
   5 IN: furnace.auth
   6
   7 HELP: <protected>
   8 { $values
   9      { "responder" "a responder" }
  10      { "protected" "a new responder" }
  11 }
  12 { $description "Wraps a responder in a protected responder. Access to the wrapped responder will be conditional upon the client authenticating with the current authentication realm." } ;
  13
  14 HELP: >>encoded-password
  15 { $values { "user" user } { "string" string } }
  16 { $description "Sets the user's password by combining it with a random salt and encoding it with the current authentication realm's checksum." } ;
  17
  18 HELP: capabilities
  19 { $var-description "Global variable holding all defined capabilities. New capabilities may be defined with " { $link define-capability } "." } ;
  20
  21 HELP: check-login
  22 { $values { "password" string } { "username" string } { "user/f" { $maybe user } } }
  23 { $description "Checks a username/password pair with the current authentication realm. Outputs a user if authentication succeeded, otherwise outputs " { $link f } "." } ;
  24
  25 HELP: define-capability
  26 { $values { "word" symbol } }
  27 { $description "Defines a new capability by adding it to the " { $link capabilities } " global variable." } ;
  28
  29 HELP: encode-password
  30 { $values
  31      { "string" string } { "salt" integer }
  32      { "bytes" byte-array }
  33 }
  34 { $description "Encodes a password with the current authentication realm's checksum." } ;
  35
  36 HELP: have-capabilities?
  37 { $values
  38      { "capabilities" "a sequence of capabilities" }
  39      { "?" "a boolean" }
  40 }
  41 { $description "Tests if the currently logged-in user possesses the given capabilities." } ;
  42
  43 HELP: logged-in-user
  44 { $var-description "Holds the currently logged-in user." } ;
  45
  46 HELP: login-required
  47 { $values
  48      { "description" string } { "capabilities" "a sequence of capabilities" }
  49 }
  50 { $description "Redirects the client to a login page." } ;
  51
  52 HELP: login-required*
  53 { $values
  54      { "description" string } { "capabilities" "a sequence of capabilities" } { "realm" "an authenticaiton realm" }
  55      { "response" response }
  56 }
  57 { $contract "Constructs an HTTP response for redirecting the client to a login page." } ;
  58
  59 HELP: protected
  60 { $class-description "The class of protected responders. See " { $link "furnace.auth.protected" } " for a description of usage and slots." } ;
  61
  62 HELP: realm
  63 { $class-description "The class of authentication realms. See " { $link "furnace.auth.realms" } " for details." } ;
  64
  65 HELP: uchange
  66 { $values { "key" symbol } { "quot" { $quotation "( old -- new )" } } }
  67 { $description "Applies the quotation to the old value of the user profile variable, and assigns the resulting value back to the variable." } ;
  68
  69 HELP: uget
  70 { $values { "key" symbol } { "value" object } }
  71 { $description "Outputs the value of a user profile variable." } ;
  72
  73 HELP: uset
  74 { $values { "value" object } { "key" symbol } }
  75 { $description "Sets the value of a user profile variable." } ;
  76
  77 HELP: username
  78 { $values { "string/f" { $maybe string } }
  79 }
  80 { $description "Outputs the currently logged-in username, or " { $link f } " if no user is logged in." } ;
  81 HELP: users
  82 { $values { "provider" "an authentication provider" } }
  83 { $description "Outputs the current authentication provider." } ;
  84
  85 ARTICLE: "furnace.auth.capabilities" "Authentication capabilities"
  86 "Every user in the authentication framework has a set of associated capabilities."
  87 $nl
  88 "Defining new capabilities:"
  89 { $subsection define-capability }
  90 "Capabilities are stored in a global variable:"
  91 { $subsection capabilities }
  92 "Protected resources can be restricted to users possessing certain capabilities only by storing a sequence of capabilities in the " { $slot "capabilities" } " slot of a " { $link protected } " instance." ;
  93
  94 ARTICLE: "furnace.auth.protected" "Protected resources"
  95 "To restrict access to authenticated clients only, wrap a responder in a protected responder."
  96 { $subsection protected }
  97 { $subsection <protected> }
  98 "Protected responders have the following two slots which may be set:"
  99 { $table
 100     { { $slot "description" } "A string identifying the protected resource for user interface purposes" }
 101     { { $slot "capabilities" } { "A sequence of capabilities; see " { $link "furnace.auth.capabilities" } } }
 102 } ;
 103
 104 ARTICLE: "furnace.auth.realm-config" "Authentication realm configuration"
 105 "Instances of subclasses of " { $link realm } " have the following slots which may be set:"
 106 { $table
 107     { { $slot "name" } "A string identifying the realm for user interface purposes" }
 108     { { $slot "users" } { "An authentication provider (see " { $link "furnace.auth.providers" } ". By default, the " { $link users-in-db } " provider is used." } }
 109     { { $slot "checksum" } { "An implementation of the checksum protocol used for verifying passwords (see " { $link "checksums" } "). The " { $link sha-256 } " checksum is used by default." } }
 110     { { $slot "users" } { "An authentication provider (see " { $link "furnace.auth.providers" } } }
 111     { { $slot "secure" } { "A boolean, that when set to a true value, forces the client to access the authentication realm via HTTPS. An attempt to access the realm via HTTP results in a redirect to the corresponding HTTPS URL. On by default." } }
 112 } ;
 113
 114 ARTICLE: "furnace.auth.providers" "Authentication providers"
 115 "The " { $vocab-link "furnace.auth" } " framework looks up users using an authentication provider. Different authentication providers can be swapped in to implement various authentication strategies."
 116 $nl
 117 "Each authentication realm has a provider stored in the " { $slot "users" } " slot. The default provider is " { $link users-in-db } "."
 118 { $subsection "furnace.auth.providers.protocol" }
 119 { $subsection "furnace.auth.providers.null" }
 120 { $subsection "furnace.auth.providers.assoc" }
 121 { $subsection "furnace.auth.providers.db" } ;
 122
 123 ARTICLE: "furnace.auth.features" "Optional authentication features"
 124 "Vocabularies having names prefixed by " { $code "furnace.auth.features" } "  implement optional features which can be enabled by calling special words. These words define new actions on an authentication realm."
 125 { $subsection "furnace.auth.features.deactivate-user" }
 126 { $subsection "furnace.auth.features.edit-profile" }
 127 { $subsection "furnace.auth.features.recover-password" }
 128 { $subsection "furnace.auth.features.registration" } ;
 129
 130 ARTICLE: "furnace.auth.realms" "Authentication realms"
 131 "The superclass of authentication realms:"
 132 { $subsection realm }
 133 "There are two concrete implementations:"
 134 { $subsection "furnace.auth.basic" }
 135 { $subsection "furnace.auth.login" }
 136 "Authentication realms need to be configured after construction."
 137 { $subsection "furnace.auth.realm-config" } ;
 138
 139 ARTICLE: "furnace.auth.users" "User profiles"
 140 "A responder wrapped in an authentication realm may access the currently logged-in user,"
 141 { $subsection logged-in-user }
 142 "as well as the logged-in username:"
 143 { $subsection username }
 144 "Values can also be stored in user profile variables:"
 145 { $subsection uget }
 146 { $subsection uset }
 147 { $subsection uchange }
 148 "User profile variables have the same restrictions on their values as session variables; see " { $link "furnace.sessions.serialize" } " for a discussion." ;
 149
 150 ARTICLE: "furnace.auth.example" "Furnace authentication example"
 151 "The " { $vocab-link "webapps.todo" } " vocabulary wraps all of its responders in a protected responder. The " { $slot "description" } " slot is set so that the login page contains the message ``You must log in to view your todo list'':"
 152 { $code
 153     <" <protected>
 154     "view your todo list" >>description">
 155 }
 156 "The " { $vocab-link "webapps.wiki" } " vocabulary defines a mix of protected and unprotected actions. One example of a protected action is that for deleting wiki pages, an action normally reserved for administrators. This action is protected with the following code:"
 157 { $code
 158     <" <protected>
 159     "delete wiki articles" >>description
 160     { can-delete-wiki-articles? } >>capabilities">
 161 }
 162 "The " { $vocab-link "websites.concatenative" } " vocabulary wraps all of its responders, including the wiki, in a login authentication realm:"
 163 { $code
 164 <" : <login-config> ( responder -- responder' )
 165     "Factor website" <login-realm>
 166         "Factor website" >>name
 167         allow-registration
 168         allow-password-recovery
 169         allow-edit-profile
 170         allow-deactivation ;">
 171 } ;
 172
 173 ARTICLE: "furnace.auth" "Furnace authentication"
 174 "The " { $vocab-link "furnace.auth" } " vocabulary implements a pluggable authentication framework."
 175 $nl
 176 "Usernames and passwords are verified using an " { $emphasis "authentication provider" } "."
 177 { $subsection "furnace.auth.providers" }
 178 "Users have capabilities assigned to them."
 179 { $subsection "furnace.auth.capabilities" }
 180 "An " { $emphasis "authentication realm" } " is a responder which manages access to protected resources."
 181 { $subsection "furnace.auth.realms" }
 182 "Actions contained inside an authentication realm can be protected by wrapping them with a responder."
 183 { $subsection "furnace.auth.protected" }
 184 "Actions contained inside an authentication realm can access the currently logged-in user profile."
 185 { $subsection "furnace.auth.users" }
 186 "Authentication realms can be adorned with additional functionality."
 187 { $subsection "furnace.auth.features" }
 188 "An administration tool."
 189 { $subsection "furnace.auth.user-admin" }
 190 "A concrete example."
 191 { $subsection "furnace.auth.example" } ;
 192
 193 ABOUT: "furnace.auth"