How to use Entra ID login block

Technical and Functional Documentation for social_auth_entra_id module.

1. Module Overview

The social_auth_entra_id module provides a login block for users to authenticate using Microsoft Entra ID. It integrates with the Microsoft Entra ID OAuth2 service to facilitate user login and manage user sessions.

2. Features

1. Entra ID Authentication: Allows users to log in using their Microsoft Entra ID.
2. Customizable Login Link: Administrators can customize the login text and add custom CSS classes.
3. User-Friendly Interface: Displays different content based on user authentication status (logged in vs. anonymous).

3. Requirements

1. Drupal 9 or 10: This module is compatible with both versions.
2. PHP 7.3 or higher: Ensure your server meets the PHP requirements.
3. Composer: To manage dependencies.

4. Installation

Step-by-Step Installation

Download the Module: download using composer

composer require 'drupal/social_auth_entra_id'

1. Download the Module: Clone the module from the repository or download it directly.

git clone <repository-url> modules/custom/social_auth_entra_id

1. Enable the Module: Navigate to the modules page in the Drupal admin interface or run the following command:

drush en social_auth_entra_id

1. Verify Installation: Ensure the module appears in the list of enabled modules.

5. Configuration

After enabling the module, configure the necessary settings:

1. Navigate to the Configuration Page: Go to /admin/config/services/entra-id/settings in your Drupal site.
2. Enter the Required API Credentials: Fill in the details for Microsoft Entra ID (Client ID, Client Secret, etc.).
3. Redirect URI (optional)
   1. Platform: Web
   2. Call back url   your-domain/user/login/entra-id/callback
4. Save Configuration: Click "Save" to apply your settings.

6. Block Configuration

The EntraIdLoginBlockBlock provides a login interface that can be added to any region of your theme.

Steps to Configure the Block:

1. Navigate to the Block Layout Page: Go to /admin/structure/block in your Drupal site.
2. Place the Block: Find "Entra ID Login Block" in the list and click "Place Block" next to it.
3. Configure the Block Settings:
4. Login Text: Enter the HTML to be displayed for the login link (e.g., <i class="fa-brands fa-microsoft"></i> Log in with Microsoft Entra ID).
5. Custom Class: Enter any additional CSS classes you want to apply to the link.
6. Save Block Configuration: Click "Save Block".

7. Usage

Once the module is installed and configured:

1. Anonymous Users: The block will display a login link allowing users to authenticate via Microsoft Entra ID.

Example Output

1. For anonymous users:

<a href="/user/login/entra-id" class="btn btn-primary"><i class="fa-brands fa-microsoft"></i> Log in with Microsoft Entra ID</a>

8. Code Structure

Key Files and Directories

1. src/Plugin/Block/EntraIdLoginBlockBlock.php: Contains the main block logic.
2. social_auth_entra_id.module: Implements hook functions and other module-wide logic.
3. config/schema/social_auth_entra_id.schema.yml: Defines the configuration schema for the module.

Code Explanation

1. EntraIdLoginBlockBlock Class: Extends BlockBase and implements the methods necessary to build the block, configure settings, and submit form values.
2. build() Method: Generates the HTML output based on the user's authentication status.
3. blockForm() and blockSubmit() Methods: Handle the configuration form for customizing the login text and CSS class.

9. Development Guidelines

1. Follow Drupal coding standards for all PHP code.
2. Ensure that all new features are covered by unit tests.
3. Maintain backward compatibility where possible.

Testing

Run the tests using PHPUnit to verify module functionality.

phpunit

10. Support and Maintenance

For support, please open an issue in the module repository or contact the maintainer directly.

License

This module is licensed under the GPL-2.0-or-later license.

This template covers all necessary aspects of the social_auth_entra_id module, from installation to usage. Be sure to customize it further based on any specific features or requirements your module might have!