Merge pull request #72 from BRACKETS-by-TRIAD/feat/add-authentication…

…-page

feat(authentication): add new page Authentication to describe all types of auth

pages/basic-features.mdx

@@ -11,7 +11,7 @@ import {
 } from "@heroicons/react/24/outline";
 
 <Cards>
-  <Card icon={<UsersIcon />} title="Social Login" href="/basic-features/social-login" />
+  <Card icon={<UsersIcon />} title="Authentication" href="/basic-features/authentication" />
   <Card icon={<UsersIcon />} title="Users" href="/basic-features/users" />
   <Card
     icon={<LanguageIcon />}

pages/basic-features/_meta.json

@@ -1,5 +1,5 @@
 {
-  "social-login": "Social Login",
+  "authentication": "Authentication",
   "users": "Users",
   "translations": "Translations",
   "roles-permissions": "Roles & Permissions",

pages/basic-features/authentication.mdx

@@ -0,0 +1,150 @@
+import Image from "components/image";
+
+# Authentication
+
+## Authentication Methods
+
+Craftable Pro supports various authentication methods to facilitate secure access for users. Each method offers distinct advantages in terms of security and convenience.
+
+### Authentication via email/password
+
+* **With Self-Registration** - Users can create new accounts through the registration form by providing necessary details such as email, and password. The domains of emails with which users can self-register can be whitelisted in the config.
+
+* **Without Self-Registration** - Only users created manually within Craftable Pro can access the system via the login form.
+
+* **Disabled** - Traditional email/password login can be entirely disabled, which can come in handy in cases when you only want users to use social logins to authenticate.
+
+To learn more about how to set up traditional login within Craftable Pro, head to the [Traditional Login](/basic-features/authentication#traditional-login) section of this page.
+
+### Authentication via social providers
+
+* **With Self-Registration** - Users can create new accounts in your app simply by authenticating via a social login provider. The domains of emails with which users can self-register can be whitelisted in the config.
+
+* **Without Self-Registration** - Only users created manually within Craftable Pro can access the system via social login providers.
+
+* **Disabled** - Social logins can be entirely disabled, if you only want to keep the traditional email/password login form for authentication.
+
+To learn more about how to set up social logins within Craftable Pro, jump to the [Social Login](/basic-features/authentication#social-login) section of this page.
+
+## Traditional Login
+
+### Self-registration
+Self-registration empowers users to autonomously create accounts, granting them access to the system while streamlining the onboarding process.
+
+<br />
+<Image alt="Registration" src="/images/register.png" />
+
+You can enable self-registration by editing the Craftable PRO config and setting `enabled` in `self_registration` to `true`.
+
+You can also set the default role for newly registered users. This is discussed more in the section [Roles & Permissions](/basic-features/roles-permissions#default-role-after-registration).
+
+To whitelist the email domains allowed for newly registered users, edit the `allowed_domains` setting. To allow any domain, set it to `['*']`.
+
+```php filename="config/craftable-pro.php"
+'self_registration' => [
+    // define if users can self register into craftable pro interface
+    'enabled' => true,
+
+    // and if enabled, then which role(s) they should have assigned by default. Use role names here.
+    // It can be a string for one role or an array for multiple roles.
+    'default_role' => 'Guest',
+    'allowed_domains' => [] // use * for allowing any domain
+],
+```
+
+## Social Login
+
+This feature empowers you to seamlessly integrate social login functionality into your application, enhancing user experience and engagement. Craftable PRO supports various popular social platforms, including Facebook, GitHub, Twitter, Apple, Google, and Microsoft, allowing your users to sign in using their preferred social accounts effortlessly.
+The functionality is powered by the [Laravel Socialite](https://laravel.com/docs/socialite) package and its extensive range of providers.
+
+### Getting Started
+
+To enable social login in your application, follow these simple steps:
+
+<div className="steps-container">
+    ### Enable social login providers
+    Select which social login providers you want to use and enable them in `config/craftable-pro.php`:
+    ```php filename="config/craftable-pro.php"
+    'social_login' => [
+        'allowed_services' => [
+            'microsoft' => false,
+            'github' => true,
+            'google' => true,
+            'twitter' => false,
+            'facebook' => false,
+            'apple' => false,
+        ],
+        'self_registration' => [
+            // define if users can self register into craftable pro interface
+            'enabled' => true,
+            // and if enabled, then which role(s) they should have assigned by default. Use role names here.
+            // It can be a string for one role or an array for multiple roles.
+            'default_role' => 'Administrator',
+            'allowed_domains' => ['craftable.pro'], // use * for allowing any domain
+        ]
+    ]
+    ```
+    ### Configure self-registration
+    When social login self-registration is enabled, users can register conveniently through various social logins. However, if disabled, users will only gain access to social login after a CraftableProUser instance has been generated for them in the Access tab.
+
+    To permit registration for emails from any domain, adjust the configuration to `'allowed_domains' => ['*']`.
+    To allow registration only for emails from a specific domain (e.g., @mydomain.com), modify the configuration to `'allowed_domains' => ['mydomain.com'].`"
+    ### Register event listeners
+    Register event listeners for your enabled providers in `app/Providers/EventServiceProvider.php`:
+    ```text filename="app/Providers/EventServiceProvider.php"
+    protected $listen = [
+        \SocialiteProviders\Manager\SocialiteWasCalled::class => [
+            \SocialiteProviders\Apple\MicrosoftExtendSocialite::class,
+            \SocialiteProviders\Apple\GitHubExtendSocialite::class,
+            \SocialiteProviders\Apple\TwitterExtendSocialite::class,
+            \SocialiteProviders\Apple\FacebookExtendSocialite::class,
+            \SocialiteProviders\Apple\GoogleExtendSocialite::class,
+            \SocialiteProviders\Apple\AppleExtendSocialite::class,
+        ]
+    ];
+    ```
+    ### Add credentials
+    Get client credentials from the providers and put them in your `.env`:
+    ```php filename=".env"
+    MICROSOFT_CLIENT_ID=
+    MICROSOFT_CLIENT_SECRET=
+    MICROSOFT_REDIRECT_URI="/admin/login/microsoft/callback"
+
+    GITHUB_CLIENT_ID=
+    GITHUB_CLIENT_SECRET=
+    GITHUB_REDIRECT_URI="/admin/login/github/callback"
+
+    GOOGLE_CLIENT_ID=
+    GOOGLE_CLIENT_SECRET=
+    GOOGLE_REDIRECT_URL="/admin/login/google/callback"
+
+    TWITTER_CLIENT_ID=
+    TWITTER_CLIENT_SECRET=
+    TWITTER_REDIRECT_URI="/admin/login/twitter/callback"
+
+    FACEBOOK_CLIENT_ID=
+    FACEBOOK_CLIENT_SECRET=
+    FACEBOOK_REDIRECT_URI="/admin/login/facebook/callback"
+
+    APPLE_CLIENT_ID=
+    APPLE_CLIENT_SECRET=
+    APPLE_REDIRECT_URI="/admin/login/apple/callback"
+    ```
+</div>
+
+### Other providers
+
+To use another existing provider, check out the [Laravel Socialite](https://laravel.com/docs/socialite) or [Laravel Socialite Providers](https://socialiteproviders.com/) documentation.
+
+To create a new custom provider, follow the steps outlined [here](https://socialiteproviders.com/contribute/#creating-a-provider).
+To enable your new provider in Craftable Pro, don't forget to add it to the config:
+```php filename="config/craftable-pro.php"
+   'social_login' => [
+        'allowed_services' => [
+            'myNewProvider' => true
+            ...
+        ],
+        ...
+    ]
+```
+as well as to implement a login button for it on the login page.

pages/basic-features/users.mdx

@@ -7,27 +7,7 @@ Craftable PRO comes with CRUD for users where you can manage who has the access
 
 ## Self-registration
 
-<br />
-<Image alt="Registration" src="/images/register.png" />
-
-You can enable self-registration by editing the Craftable PRO config and setting `enabled` in `self_registration` to `true`.
-
-You can also set the default role for newly registered users. This is discussed more in the section [Roles & Permissions](/basic-features/roles-permissions#default-role-after-registration).
-
-To whitelist the email domains allowed for newly registered users, edit the `allowed_domains` setting. To allow any domain, set it to `['*']`.
-
-```php filename="config/craftable-pro.php"
- 'self_registration' => [
-        // define if users can self register into craftable pro interface
-        'enabled' => true,
-
-        // and if enabled, then which role(s) they should have assigned by default. Use role names here.
-        // It can be a string for one role or an array for multiple roles.
-        'default_role' => 'Guest',
-
-        'allowed_domains' => [] // use * for allowing any domain
-    ],
-```
+To read about self registration, head to [Traditional Login](/basic-features/authentication#traditional-login) page.
 
 ## Verification