README

Styling Requirement

Bootstrap v5

Project Purpose

The Bundle is designed to provide seamless authentication using social login providers such as Apple and Google. It enables users to authenticate securely via OAuth, ensuring a smooth and standardized login experience. The system verifies the identity of users through token-based authentication and integrates with the application's user management system.

Theme

To add the templates of the bundle, please add the following entry to your theme:

@EsonoSocialLoginBundle/Resources/views

Modifications / Special Case

You need to update the edit-profile-password.view.php as it is not possible to update / edit the existing password on a social login user. Maybe you can integrate a text like this:

Ihr Kunden-Konto ist mit einem Social Login (Apple oder Google) verknüpft.
Um ein (neues) Passwort zu vergeben, nutzen Sie bitte die Passwort-Vergessen Funktion.

Main Components

The project is structured into several key components that interact to facilitate authentication and user management.

1. Controller Layer

• SocialLoginController.php: Manages authentication requests, processes login responses, and redirects users after authentication.

2. Data Models

• ApplePayload.php & GooglePayload.php: Represent authentication responses from Apple and Google.
• Payload.php: A base class ensuring consistency in handling authentication responses.

3. Entity Layer (Database Representation)

• SocialLoginExtranetUser.php: Maps social login data to user accounts.
• SocialLoginMTExtranetCore.php: Stores metadata related to social login sessions.

4. Service Layer

• SocialLoginSettingsDataAccess.php: Handles social login configuration settings.
• CustomerDataAccess.php: Retrieves and updates customer-related authentication data.

5. Token Verification & Security

• AppleClientSecretGenerator.php: Generates client secrets for Apple authentication.

How Components Interact

1. The user clicks the social login button (Apple or Google), triggering the authentication request.
2. The request is handled by SocialLoginController.php, which redirects the user to the provider’s OAuth endpoint.
3. The provider authenticates the user and returns an OAuth token.
4. The Payload model extracts and processes the token data.
5. The Service Layer verifies the token and determines whether the user should be logged in or registered.
6. The Entity Layer persists user data in the database, ensuring session continuity.

Token Verification Process

Token verification is a crucial security step that ensures the authenticity of authentication responses.

1. Retrieving the Token

After successful authentication, Apple or Google provides an ID token (JWT). This token contains claims about the authenticated user.

2. Decoding and Validating the Token

Google Token Verification

• Retrieve the ID token from Google’s authentication response.
• Decode the JWT and extract its claims.
• Validate the token's signature using Google’s public keys.
• Verify the claims (iss, aud, exp, etc.).
• Extract user details for further processing.

Apple Token Verification

• Fetch Apple’s public keys from https://appleid.apple.com/auth/keys.
• Validate the JWT signature against Apple’s keys.
• Check that required claims (sub, aud, exp) are valid.
• Validate the client secret against the stored credentials.

3. Processing User Data

• Extract user data (ID, email, etc.) and match it with existing records.
• If a user exists, they are logged in.
• If not, a new user account is created.

4. Handling Token Expiry and Errors

• Ensure the token has not expired (exp claim).
• Handle invalid or tampered tokens gracefully.
• If supported, use refresh tokens for session continuity.

How to Obtain Required Authentication Credentials

Apple Credentials

1. Generating the Apple Client ID

1. Visit: Apple Developer Account
2. Navigate to Certificates, Identifiers & Profiles → Identifiers.
3. Create a new Identifier and select App IDs.
4. Enable the capability Sign in with Apple.
5. Note the Client ID generated.

2. Obtaining the Apple App ID

1. Go to Apple Developer Account.
2. Navigate to Certificates, Identifiers & Profiles → Identifiers.
3. Create a new App ID and ensure Sign in with Apple is enabled.

3. Setting up Website-URL and Return Url

1. Navigate to Certificates, Identifiers & Profiles → Identifiers.
2. Change Top-Right from App IDs to Service ID
3. Select the previously created Primary App ID.
4. Enable Sign in with Apple and press the Button Configure

5. Configure the Website Urls. There are 2 elements you need to configure

   a) Website-URL (Domains & Subdomains) Example: genialokal.de or genialokal.stage.esono.net

   b) Return URL's: Full Return Url's including Protocol and Path: Example: https://genialokal.de/social-login/apple/callback

6. Save the generated App ID for integration.

3. Retrieving the Apple Key ID

1. Go to Certificates, Identifiers & Profiles.
2. Create a new Authentication Key.
3. Select Sign in with Apple as the service.
4. Save the Key ID generated.

4. Generating the Apple Client Secret (Private Key File)

1. Navigate to Apple Developer Key Management.
2. Generate a new key for Sign in with Apple.
3. Download the private key (.p8 file) securely.
4. Use this key to generate the client secret in your application.

Google Credentials

1. Generating the Google Client ID

1. Visit the Google Cloud Console.
2. Select an existing project or create a new one.
3. Navigate to APIs & Services → Credentials.
4. Click Create Credentials and choose OAuth 2.0 Client ID.
5. Set the application type to Web Application.
6. Enter the authorized redirect URIs (e.g., https://yourdomain.com/auth/google/callback).
7. Click Create, and your Client ID will be generated.
8. Save the Client ID and Client Secret securely.

Examples of Different Apple Login Responses

1. User Shares Email:

   {
       "email": "user@example.com",
       "sub": "000123456789ABCDE"
   }
   

2. User Uses Private Email Relay:

   {
       "email": "random@privaterelay.appleid.com",
       "sub": "000123456789ABCDE"
   }