diff --git a/assets/images/2fa-setup.jpg b/assets/images/2fa-setup.jpg new file mode 100644 index 0000000..0a27261 Binary files /dev/null and b/assets/images/2fa-setup.jpg differ diff --git a/assets/images/social-providers-screen.jpg b/assets/images/social-providers-screen.jpg new file mode 100644 index 0000000..329e7c2 Binary files /dev/null and b/assets/images/social-providers-screen.jpg differ diff --git a/content/docs/config/files.md b/content/docs/config/files.md index d9c9822..3a85d2f 100644 --- a/content/docs/config/files.md +++ b/content/docs/config/files.md @@ -14,158 +14,24 @@ The DevDojo Auth package includes several configuration files that allow you to ### 1. appearance.php -This file allows you to customize the look and feel of the authentication pages. - -#### Example Configuration: - -```php -return [ - 'logo' => '/path/to/logo.png', - 'background_color' => '#f8f9fa', - 'primary_color' => '#007bff', - 'font' => 'Roboto, sans-serif', -]; -``` - -### 2. descriptions.php - -This file contains descriptions used in the authentication process, allowing you to modify them as needed. - -#### Example Configuration: +This file allows you to customize the look and feel of the authentication pages. You may manually modify this file if you would like to make any updates, but it's easier to make those changes from the Auth Setup page. -```php -return [ - 'login' => 'Please enter your login credentials', - 'register' => 'Create a new account', -]; -``` +### 2. language.php -### 3. fields.php +This file contains the language copy that will be used throughout your authentication. You can modify the tone of your copy to sound more like you. -Define custom fields for user registration and other forms in this configuration file. +### 3. providers.php -#### Example Configuration: +This is a list of all the available providers you can include in your authentication. When you toggle the network on/off it will change the `active` value to true/false and will show/hide that network in your authentication. -```php -return [ - 'registration' => [ - 'username' => [ - 'type' => 'text', - 'label' => 'Username', - 'required' => true, - ], - 'phone' => [ - 'type' => 'text', - 'label' => 'Phone Number', - 'required' => false, - ], - ], -]; -``` +If you see some additional providers available from the Socialite Providers website, but it's not listed in this config. You may manually add it to the array and it will show up in the Auth Setup page allowing you to enable/disable that social network. -### 4. language.php +### 4. settings.php -Configure language settings and translations for your authentication pages. +This file contains settings that will change the way your authenticaiton functions. -#### Example Configuration: +> You'll also notice a descriptions.php file, which is only used internally in the Auth Setup pages, so this file can be ignored on your part. -```php -return [ - 'default' => 'en', - 'available' => ['en', 'es', 'fr'], -]; -``` - -### 5. pages.php - -Manage the settings for the various authentication pages. - -#### Example Configuration: - -```php -return [ - 'login' => [ - 'title' => 'Login', - 'description' => 'Please login to your account', - ], - 'register' => [ - 'title' => 'Register', - 'description' => 'Create a new account', - ], -]; -``` - -### 6. providers.php - -Set up third-party OAuth providers for social authentication. - -#### Example Configuration: - -```php -return [ - 'google' => [ - 'client_id' => env('GOOGLE_CLIENT_ID'), - 'client_secret' => env('GOOGLE_CLIENT_SECRET'), - ], - 'facebook' => [ - 'client_id' => env('FACEBOOK_CLIENT_ID'), - 'client_secret' => env('FACEBOOK_CLIENT_SECRET'), - ], -]; -``` - -### 7. settings.php - -General settings for the authentication package, including enabling features like two-factor authentication (2FA). - -#### Example Configuration: - -```php -return [ - '2fa' => [ - 'enabled' => true, - 'secret_key_length' => 16, - ], -]; -``` - -## Making Changes via /auth/setup - -When you visit the `/auth/setup` page, you can customize the various settings for the DevDojo Auth package. The changes you make on this page will be automatically reflected in the corresponding configuration files within the `config/devdojo/auth` directory. - -### Example Workflow: - -1. **Visit the `/auth/setup` Page:** - Navigate to the `/auth/setup` page in your browser. Here, you will find options to customize the appearance, fields, language, and other settings for your authentication pages. - -2. **Make Changes:** - Adjust the settings according to your preferences. For example, you can change the logo, update the primary color, or enable additional registration fields. - -3. **Save Changes:** - Once you save your changes, they will be written to the corresponding configuration files in the `config/devdojo/auth` directory. For instance, if you update the primary color, this change will be reflected in the `appearance.php` file. - -## Additional Information - -### Environment Variables - -For sensitive information such as API keys and client secrets, it is recommended to use environment variables. The DevDojo Auth package uses the `env` function to retrieve these values from your `.env` file. - -### Example .env Configuration: - -``` -GOOGLE_CLIENT_ID=your-google-client-id -GOOGLE_CLIENT_SECRET=your-google-client-secret - -FACEBOOK_CLIENT_ID=your-facebook-client-id -FACEBOOK_CLIENT_SECRET=your-facebook-client-secret -``` - -### Customization Flexibility - -The DevDojo Auth package provides a high level of customization flexibility through its configuration files. This allows you to tailor the authentication process to fit the specific needs of your application and users. - -## Conclusion - -By understanding and utilizing the configuration files provided by the DevDojo Auth package, you can easily customize and manage the authentication experience in your application. The `/auth/setup` page provides a user-friendly interface for making these changes, ensuring that your configurations are always up to date and reflecting your preferences. +Remember, you can make modifications to these configs manually or via the Auth Setup, but it's probably best practice to modify it in the setup page to prevent any conflicts from future releases. diff --git a/content/docs/config/github-action.md b/content/docs/config/github-action.md index 381fa2b..a552573 100644 --- a/content/docs/config/github-action.md +++ b/content/docs/config/github-action.md @@ -8,171 +8,26 @@ description: DevDojo Auth ships with a Github action that can help gaurantee tha ## Introduction -The DevDojo Auth package includes a GitHub Action workflow that helps you ensure your application is fully functional. This workflow is designed to automate the testing process, running tests on every push and pull request to your repository. By integrating this workflow, you can guarantee that your application remains reliable and any changes made do not break existing functionality. +This package includes a GitHub Action workflow that helps you ensure your authentication is fully functional. This action will run every time you make a new pull request to be merged into the `main` branch. If all the checks pass in the workflow you know that your authentication is fully operational. -## Workflow Overview +## Publish the CI Workflow File -### Location +In order to get the Github Action published to your project you will need to run the following command: -The workflow file is located in the `.github/workflows/tests.yml` directory of your repository. +
php artisan vendor:publish --tag=auth:ci
-### Purpose +This will place a new file located inside your application at `.github/workflows/auth.yml` -The primary purpose of this workflow is to automate the testing process. It runs tests in a clean environment to verify that your application works as expected. This helps catch issues early in the development process, reducing the chances of bugs making it to production. +## Workflow Errors -## How the Workflow Works +If you receive Authentication errors when pushing new code you may want to run the tests locally so that way you can debug what is going on. Run the following command: -### Trigger Events - -The workflow is triggered on the following events: -- `push`: Runs the workflow on every push to the repository. -- `pull_request`: Runs the workflow on every pull request. - -### Workflow Steps - -The workflow consists of several steps, each performing specific tasks to set up the environment and run the tests. - -#### Example Workflow Configuration: - -```yaml -name: Run tests - -on: [push, pull_request] - -jobs: - test: - runs-on: ubuntu-latest - - steps: - - name: Checkout code - uses: actions/checkout@v2 - - - name: Set up PHP - uses: shivammathur/setup-php@v2 - with: - php-version: '7.4' - - - name: Install dependencies - run: composer install --prefer-dist --no-progress --no-suggest - - - name: Copy .env file - run: cp .env.example .env - - - name: Generate application key - run: php artisan key:generate - - - name: Run migrations - run: php artisan migrate - - - name: Run tests - run: php artisan test ``` - -### Step-by-Step Breakdown - -1. **Checkout Code:** - ```yaml - - name: Checkout code - uses: actions/checkout@v2 - ``` - This step checks out your repository code so that the workflow can access it. - -2. **Set Up PHP:** - ```yaml - - name: Set up PHP - uses: shivammathur/setup-php@v2 - with: - php-version: '7.4' - ``` - This step sets up the PHP environment, specifying the PHP version to use. - -3. **Install Dependencies:** - ```yaml - - name: Install dependencies - run: composer install --prefer-dist --no-progress --no-suggest - ``` - This step installs the PHP dependencies required for your application. - -4. **Copy .env File:** - ```yaml - - name: Copy .env file - run: cp .env.example .env - ``` - This step copies the example environment file to create the `.env` file. - -5. **Generate Application Key:** - ```yaml - - name: Generate application key - run: php artisan key:generate - ``` - This step generates the application key required by Laravel. - -6. **Run Migrations:** - ```yaml - - name: Run migrations - run: php artisan migrate - ``` - This step runs the database migrations to set up the database schema. - -7. **Run Tests:** - ```yaml - - name: Run tests - run: php artisan test - ``` - This step runs the application tests to ensure everything is working correctly. - -## Additional Information - -### Customizing the Workflow - -You can customize the workflow to fit the specific needs of your project. For example, you might want to test against multiple PHP versions or include additional setup steps for services like MySQL or Redis. - -### Example: Testing Against Multiple PHP Versions - -```yaml -jobs: - test: - runs-on: ubuntu-latest - - strategy: - matrix: - php-version: ['7.4', '8.0', '8.1'] - - steps: - - name: Checkout code - uses: actions/checkout@v2 - - - name: Set up PHP - uses: shivammathur/setup-php@v2 - with: - php-version: \${{ matrix.php-version }} - - # ... remaining steps -``` - -### Example: Adding MySQL Service - -```yaml -services: - mysql: - image: mysql:5.7 - env: - MYSQL_ROOT_PASSWORD: root - MYSQL_DATABASE: test - options: >- - --health-cmd "mysqladmin ping --silent" - --health-interval 10s - --health-timeout 5s - --health-retries 3 - ports: - - 3306:3306 - -steps: -- name: Wait for MySQL - run: dockerize -wait tcp://localhost:3306 -timeout 1m +./vendor/bin/pest ./vendor/devdojo/auth/tests ``` -### Conclusion +This will attempt to run your tests locally. -By integrating the GitHub Action workflow provided by the DevDojo Auth package, you can automate your testing process and ensure that your application remains functional with every change. Customizing the workflow allows you to tailor it to the specific needs of your project, providing flexibility and robustness in your CI/CD pipeline. +## Troubleshooting +If you find an error in the CI workflow you may open an Issue on Github; however, if the issue is related directly to your specific setup we may end up closing the issue as it might be out of scope for the support we'll provide. \ No newline at end of file diff --git a/content/docs/config/social-providers.md b/content/docs/config/social-providers.md index 807533b..4075fcb 100644 --- a/content/docs/config/social-providers.md +++ b/content/docs/config/social-providers.md @@ -8,37 +8,37 @@ description: Allow users to authenticate with many Social Providers ## Introduction -The DevDojo Auth package supports integration with various social authentication providers like Google, Facebook, and Twitter. This allows users to log in using their social media accounts, making the authentication process more convenient and secure. +Auth supports out-of-the-box social authentication. This allows users to log in using their social media accounts, making the authentication process more convenient and secure. -## Setting Up Social Providers +## Included Providers + +The following providers are included by default and ready-to-use (after adding credentials): -To enable social authentication, follow these steps: + - Facebook + - Twitter + - LinkedIn + - Google + - GitHub + - GitLab + - Bitbucket + - Slack -### 1. Retrieve Client Credentials +These are all part of Laravel Socialite. If you want to use additional providers that are not listed above, you'll need to install another package called Socialite Providers. -For each social provider you want to enable, you need to retrieve the `CLIENT_ID` and `CLIENT_SECRET`. These credentials are provided by the social platform when you register your application with them. +## Socialite Providers Package -#### Example: +Socialite Providers is a third-party package available at https://socialiteproviders.com/. This package includes a ton of providers. You will need to install a package for each provider you want to include. For instance, if you want to use the Apple Service provider, you will need to install the package here. -- **Google:** - - Go to the [Google Developers Console](https://console.developers.google.com/). - - Create a new project or select an existing project. - - Navigate to the **Credentials** page. - - Click on **Create Credentials** and select **OAuth 2.0 Client IDs**. - - Follow the steps to configure the consent screen and application. - - Retrieve your `CLIENT_ID` and `CLIENT_SECRET`. +After installing the socialite providers you want to use, you can then move on to the rest of the setup. -- **Facebook:** - - Go to the [Facebook Developers](https://developers.facebook.com/) site. - - Create a new app or select an existing app. - - Navigate to **Settings** > **Basic**. - - Retrieve your `App ID` (CLIENT_ID) and `App Secret` (CLIENT_SECRET). -### 2. Configure Providers +## Setting Up Social Providers + +To setup a specific social auth provider, you will need to retrieve two keys for each. The `CLIENT_ID` and the `CLIENT_SECRET`. These credentials can be retrieved from each social network and each network has a different process for retrieving these keys. We will not go into detail on how to retrieve these keys; however, you can do a search for `Setting up oAuth with network` and you should find steps that will help you retrieve each of these. -Add your provider credentials to the `.env` file. The credentials will be retrieved from the environment variables and used in the `config/devdojo/auth/providers.php` file. +## Add keys to your .env -#### Example .env Configuration: +When you have your `CLIENT_ID` and `CLIENT_SECRET` for each social provider, you will need to open your `.env` file and add those credentials, like so: ``` GOOGLE_CLIENT_ID=your-google-client-id @@ -48,92 +48,25 @@ FACEBOOK_CLIENT_ID=your-facebook-client-id FACEBOOK_CLIENT_SECRET=your-facebook-client-secret ``` -### 3. Enable Providers in Setup Page +The example above is what it would look like to add your social authentication with `GOOGLE` and `FACEBOOK`. -After adding the credentials to the `.env` file, you need to enable them in the setup page of your application. This will activate the social providers and make them available for user authentication. - -### 4. Visual Indicators +### Visual Indicators In the setup screen, you will see a list of social providers with key icons next to them: -- **Green Key Icon:** Indicates that the `CLIENT_ID` and `CLIENT_SECRET` have been correctly configured for the provider. -- **Red Key Icon:** Indicates that the `CLIENT_ID` and `CLIENT_SECRET` are missing or incorrect. - -Make sure to configure the credentials properly to ensure the icons turn green, indicating that the provider is correctly set up. - -### 5. Update Routes - -To handle social authentication routes, update your application's routes file to include the necessary routes for social authentication. - -#### Example Routes: - -```php -use DevDojo\Auth\Http\Controllers\SocialController; - -Route::get('login/{provider}', [SocialController::class, 'redirect']); -Route::get('login/{provider}/callback', [SocialController::class, 'callback']); -``` - -### 6. Controller Methods - -The `SocialController` contains methods to handle the redirection to the social provider and the callback after authentication. + -#### Example Controller Methods: - -```php -namespace DevDojo\Auth\Http\Controllers; - -use Illuminate\Http\Request; -use Laravel\Socialite\Facades\Socialite; - -class SocialController extends Controller -{ - public function redirect($provider) - { - return Socialite::driver($provider)->redirect(); - } - - public function callback($provider) - { - $user = Socialite::driver($provider)->user(); - // Handle user information and login - } -} -``` - -### 7. Handling User Information - -Once the user is authenticated via a social provider, you can handle the user information returned by the provider. This typically involves creating a new user account or updating an existing account with the information provided. - -#### Example Handling: - -```php -public function callback($provider) -{ - $socialUser = Socialite::driver($provider)->user(); - - $user = User::updateOrCreate( - ['provider_id' => $socialUser->getId()], - [ - 'name' => $socialUser->getName(), - 'email' => $socialUser->getEmail(), - 'avatar' => $socialUser->getAvatar(), - 'provider' => $provider, - ] - ); - - Auth::login($user, true); - - return redirect()->intended('/home'); -} -``` +- **Green Key Icon:** Indicates that the `CLIENT_ID` and `CLIENT_SECRET` have been added. +- **Red Key Icon:** Indicates that the `CLIENT_ID` and `CLIENT_SECRET` are missing. -### 8. Testing Social Authentication +### Testing Out Social Authentication -After setting up and configuring your social providers, it's crucial to test the authentication process to ensure everything works correctly. Try logging in with each configured social provider and verify that the process completes successfully. +After you add the `CLIENT_ID` and `CLIENT_SECRET` for the social providers you'll then be able to toggle that social provider and see it on the Login/Register pages. -### Conclusion +If everything is setup correctly, you'll be able to click the Social Provider button and be authenticated with that user/network. -By following these steps, you can enable social authentication in your application using the DevDojo Auth package. Properly configured social authentication provides a seamless login experience for your users and enhances the security of your application. +Remember that everything needs to be setup correctly. In the social network setup page you'll need to make sure your local URL's are included correctly, even and HTTPS/HTTP mis-match can break the social authentication functionality. +## Show Social Providers on Login: +Inside of your authentication setup page, you will see an option titled: **Login Show Social Providers**. If this is toggled off, the social provider buttons will not be visible by default. If a user then enters their email and it's associated with a social network, that network button will show up in place of the Email/Identifer input. \ No newline at end of file diff --git a/content/docs/config/two-factor-auth.md b/content/docs/config/two-factor-auth.md index 562079f..4762c0c 100644 --- a/content/docs/config/two-factor-auth.md +++ b/content/docs/config/two-factor-auth.md @@ -9,119 +9,20 @@ description: Learn about Two-Factor Auth and how to enable it for your applicati Two-factor authentication (2FA) adds an extra layer of security to user accounts. The DevDojo Auth package provides built-in support for 2FA, allowing site creators to enhance the security of their application by requiring users to provide a second form of authentication. -## Enabling 2FA +## Site-Owner Enable/Disable -### Site-Wide Activation - -The site creator can choose to enable 2FA site-wide or keep it disabled. To enable 2FA site-wide, you need to configure the `settings.php` file in the `config/devdojo/auth` directory. - -#### Example Configuration: - -```php -return [ - '2fa' => [ - 'enabled' => true, - 'secret_key_length' => 16, - ], -]; -``` +The site owner can choose to enable 2FA site-wide or keep it disabled. There is a toggle button in the Auth Setup page that will allow you to enable/disable site-wide. If it's disabled users will not be given the option to add 2FA; however, if it's enabled the user will be allowed to add 2FA to their account. ### User-Level Activation -If 2FA is activated site-wide, users will have the option to enable 2FA for their individual accounts. They can visit the `/user/two-factor-authentication` page to set up 2FA. - -## Setting Up 2FA for Users - -### Updating User Model - -To enable 2FA for users, update your user model to use the `TwoFactorAuthenticatable` trait. - -#### Example User Model: - -```php -use DevDojo\Auth\Traits\TwoFactorAuthenticatable; - -class User extends Authenticatable -{ - use TwoFactorAuthenticatable; -} -``` - -### Enabling 2FA for Users - -When 2FA is enabled, users can visit the `/user/two-factor-authentication` page to activate it for their accounts. This page will guide them through the process of setting up 2FA using an authenticator app like Google Authenticator. - -### Generating QR Code and Secret Key - -The DevDojo Auth package will generate a QR code and a secret key for the user. The user can scan the QR code using their authenticator app, which will then generate authentication codes. - -#### Example Controller Method for Enabling 2FA: - -```php -public function enableTwoFactorAuth(Request $request) -{ - $user = $request->user(); +If 2FA is activated site-wide, users will have the option to enable 2FA for their individual accounts. They can visit the `/user/two-factor-authentication` page to set up 2FA. This page will guide them through the process of setting up 2FA using an authenticator app like Google Authenticator. - // Generate QR code and secret key - $qrCode = $user->generateTwoFactorQrCode(); - $secretKey = $user->getTwoFactorSecretKey(); + - return view('two-factor-authentication.setup', compact('qrCode', 'secretKey')); -} -``` +If you are using Jetstream, the users will have the availability to enable/disable 2FA from their profile page. -## Using 2FA for Authentication ### Logging In with 2FA After 2FA is activated, users will be prompted to enter an authentication code after they log in. They can generate this code using their authenticator app. -#### Example Middleware for 2FA: - -```php -namespace DevDojo\Auth\Http\Middleware; - -use Closure; - -class TwoFactorEnabled -{ - public function handle($request, Closure $next) - { - if ($request->user()->isTwoFactorEnabled()) { - return redirect('/user/two-factor-authentication-challenge'); - } - - return $next($request); - } -} -``` - -### Authenticating with 2FA - -When the user is prompted, they will enter the authentication code generated by their authenticator app. The DevDojo Auth package will verify the code and grant access if it is correct. - -#### Example Controller Method for Verifying 2FA Code: - -```php -public function verifyTwoFactorAuthCode(Request $request) -{ - $request->validate(['code' => 'required|numeric']); - - $user = $request->user(); - - if ($user->verifyTwoFactorAuthCode($request->code)) { - // Code is correct, grant access - return redirect('/home'); - } - - // Code is incorrect, redirect back with error - return redirect()->back()->withErrors(['code' => 'The provided authentication code is incorrect.']); -} -``` - -## Conclusion - -By enabling and configuring two-factor authentication using the DevDojo Auth package, site creators can significantly enhance the security of their application. Users will benefit from an additional layer of protection, making it harder for unauthorized individuals to gain access to their accounts. - -Following these steps ensures that 2FA is properly set up and functional, providing peace of mind for both site creators and users. -