From 40ccde840371b1b9d91323074b2f1825611f1bd1 Mon Sep 17 00:00:00 2001 From: Kristina Odziomkova Date: Thu, 4 Jan 2024 15:45:40 +0100 Subject: [PATCH] feat(authentication): add new page Authentication to describe all types of auth --- pages/basic-features.mdx | 2 +- pages/basic-features/_meta.json | 2 +- pages/basic-features/authentication.mdx | 150 ++++++++++++++++++++++++ pages/basic-features/social-login.mdx | 95 --------------- pages/basic-features/users.mdx | 16 +-- 5 files changed, 153 insertions(+), 112 deletions(-) create mode 100644 pages/basic-features/authentication.mdx delete mode 100644 pages/basic-features/social-login.mdx diff --git a/pages/basic-features.mdx b/pages/basic-features.mdx index abdbfa8..eb4adf6 100644 --- a/pages/basic-features.mdx +++ b/pages/basic-features.mdx @@ -11,7 +11,7 @@ import { } from "@heroicons/react/24/outline"; - } title="Social Login" href="/basic-features/social-login" /> + } title="Authentication" href="/basic-features/authentication" /> } title="Users" href="/basic-features/users" /> } diff --git a/pages/basic-features/_meta.json b/pages/basic-features/_meta.json index 4937b5f..a10b2f9 100644 --- a/pages/basic-features/_meta.json +++ b/pages/basic-features/_meta.json @@ -1,5 +1,5 @@ { - "social-login": "Social Login", + "authentication": "Authentication", "users": "Users", "translations": "Translations", "roles-permissions": "Roles & Permissions", diff --git a/pages/basic-features/authentication.mdx b/pages/basic-features/authentication.mdx new file mode 100644 index 0000000..454e78a --- /dev/null +++ b/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. + +
+Registration + +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: + +
+ ### 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" + ``` +
+ +### 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. \ No newline at end of file diff --git a/pages/basic-features/social-login.mdx b/pages/basic-features/social-login.mdx deleted file mode 100644 index 2f1cd3f..0000000 --- a/pages/basic-features/social-login.mdx +++ /dev/null @@ -1,95 +0,0 @@ -import { Callout, Tabs, Tab } from "nextra-theme-docs"; - -# 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: - -
-### Select which services 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 - ] - ] -``` -### Social login 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 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, - ] -]; -``` -### 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" -``` -
- -## 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. \ No newline at end of file diff --git a/pages/basic-features/users.mdx b/pages/basic-features/users.mdx index ff45f25..484d294 100644 --- a/pages/basic-features/users.mdx +++ b/pages/basic-features/users.mdx @@ -7,21 +7,7 @@ Craftable PRO comes with CRUD for users where you can manage who has the access ## Self-registration -
-Registration - -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). - -```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', - ], -``` +To read about self registration, head to [Traditional Login](/basic-features/authentication#traditional-login) page. ## Verification