Merge branch 'lovasoa:main' into menu-item-icon

Author: pchemguy

examples/official-site/examples/authentication/basic_auth.sql

@@ -0,0 +1,18 @@
+SELECT 'authentication' AS component,
+    case sqlpage.basic_auth_username()
+        when 'admin'
+            then '$argon2i$v=19$m=8,t=1,p=1$YWFhYWFhYWE$oKBq5E8XFTHO2w' -- the password is 'password'
+        when 'user'
+            then '$argon2i$v=19$m=8,t=1,p=1$YWFhYWFhYWE$qsrWdjgl96ooYw' -- the password is 'user'
+    end AS password_hash, -- this is a hash of the password 'password'
+    sqlpage.basic_auth_password() AS password; -- this is the password that the user entered in the browser popup
+
+select 'dynamic' as component, properties FROM example WHERE component = 'shell' LIMIT 1;
+
+select 'text' as component, '
+# Authentication
+
+Read the [source code](//github.com/lovasoa/SQLpage/blob/main/examples/official-site/examples/authentication/basic_auth.sql) for this demo.
+' as contents_md;
+
+select 'alert' as component, 'info' as color, CONCAT('You are logged in as ', sqlpage.basic_auth_username()) as title;

examples/official-site/sqlpage/migrations/07_authentication.sql

@@ -54,32 +54,70 @@ VALUES (
 
 ### Usage with HTTP basic authentication
 
-The most basic usage of the authentication component is to let SQLPage handle the authentication through HTTP basic authentication.
-This is the simplest way to password-protect a page, but it is not very user-friendly, because the browser will show an unstyled popup asking for the username and password.
-The username and password entered by the user will be accessible in your SQL code using the
+The most basic usage of the authentication component is with the
 [`sqlpage.basic_auth_username()`](functions.sql?function=basic_auth_username#function) and
 [`sqlpage.basic_auth_password()`](functions.sql?function=basic_auth_password#function) functions.
+The component will check if the provided password matches the stored [password hash](/examples/hash_password.sql),
+and if not, it will prompt the user to enter a password in a browser popup:
 
-The [`sqlpage.hash_password`](functions.sql?function=hash_password#function) function can be used to 
-[generate a secure password hash](/examples/hash_password.sql) that you need to store in your database.
+```sql
+SELECT ''authentication'' AS component,
+    ''$argon2i$v=19$m=8,t=1,p=1$YWFhYWFhYWE$oKBq5E8XFTHO2w'' AS password_hash, -- this is a hash of the password ''password''
+    sqlpage.basic_auth_password() AS password; -- this is the password that the user entered in the browser popup
+```
+
+You can [generate a password hash using the `hash_password` function](/examples/hash_password.sql).
+
+If you want to have multiple users with different passwords,
+you could store them with their password hashes in the database,
+or just hardcode them use a `CASE` statement:
 
 ```sql
 SELECT ''authentication'' AS component,
-    ''$argon2id$v=19$m=16,t=2,p=1$TERTd0lIcUpraWFTcmRQYw$+bjtag7Xjb6p1dsuYOkngw'' AS password_hash, -- generated using sqlpage.hash_password
+    case sqlpage.basic_auth_username()
+        when ''admin''
+            then ''$argon2i$v=19$m=8,t=1,p=1$YWFhYWFhYWE$oKBq5E8XFTHO2w'' -- the password is ''password''
+        when ''user''
+            then ''$argon2i$v=19$m=8,t=1,p=1$YWFhYWFhYWE$qsrWdjgl96ooYw'' -- the password is ''user''
+    end AS password_hash, -- this is a hash of the password ''password''
     sqlpage.basic_auth_password() AS password; -- this is the password that the user entered in the browser popup
 ```
 
-You can [try the hash_password function out here](/examples/hash_password.sql).
+Try this example online: [SQL Basic Auth](/examples/authentication/basic_auth.sql).
+
+### Advanced user session management
+
+*Basic auth* is the simplest way to password-protect a page,
+but it is not very flexible nor user-friendly,
+because the browser will show an unstyled popup asking for the username and password.
 
-### Usage with a login form
+For more advanced authentication, you can store user information and user sessions in your database.
+You can then use the [`form`](components.sql?component=form#component) component to create a custom login form.
+When the user submits the form, you check if the password is correct using the `authentication` component.
+You then store a unique string of numbers and letters (a session token) both in the user''s browser
+using the [`cookie`](components.sql?component=cookie#component) component and in your database.
+Then, in all the pages that require authentication, you check if the cookie is present and matches the session token in your database.
 
-The most basic usage of the authentication component is to simply check if the user has sent the correct password, and if not, redirect them to a login page: 
+You can check if the user has sent the correct password in a form, and if not, redirect them to a login page.
+
+Create a login form in a file called `login.sql`:
+
+```sql
+select ''form'' as component, ''Authentication'' as title, ''Log in'' as validate, ''create_session_token.sql'' as action;
+select ''Username'' as name, ''admin'' as placeholder;
+select ''Password'' as name, ''admin'' as placeholder, ''password'' as type;
+```
+
+And then, in `create_session_token.sql` :
 
 ```sql
 SELECT ''authentication'' AS component,
     ''login.sql'' AS link,
     ''$argon2id$v=19$m=16,t=2,p=1$TERTd0lIcUpraWFTcmRQYw$+bjtag7Xjb6p1dsuYOkngw'' AS password_hash, -- generated using sqlpage.hash_password
     :password AS password; -- this is the password that the user sent through our form
+
+-- The code after this point is only executed if the user has sent the correct password
+
 ```
 
 and in `login.sql` :