UNDER INITIAL DEVELOPMENT

• Once this extension is fully developed and tested, this message will be removed and a release 1.0.0 will be made.

Spearstone Auth Extension for Joomla 4

The spearstone_auth extension integrates an external OIDC-compliant Identity Provider (IDP), such as Ory Hydra, into Joomla 4. It allows you to control authentication and authorization via the IDP while leveraging Joomla's group-based access control. The extension consists of a system plugin and an administrator component.

Table of Contents

• 1. Extension Structure
• 2. Installation Instructions
  • 2.1. Setup and Packaging
  • 2.2. Installation
• 3. Post-Installation Configuration
• 4. Testing the Extension

---

1. Extension Structure

spearstone_auth/
├── administrator/
│   └── components/
│       └── com_spearstoneauth/
│           ├── spearstoneauth.xml
│           ├── config.xml
│           ├── controller.php
│           ├── models/
│           │   └── configuration.php
│           ├── views/
│           │   └── configuration/
│           │       ├── view.html.php
│           │       └── tmpl/
│           │           └── default.php
│           └── language/
│               └── en-GB/
│                   ├── en-GB.com_spearstoneauth.ini
│                   └── en-GB.com_spearstoneauth.sys.ini
├── plugins/
    └── system/
        └── spearstoneauth/
            ├── spearstoneauth.xml
            ├── spearstoneauth.php
            ├── access/
            │   └── SpearstoneAccess.php
            ├── composer.json
            ├── vendor/ (generated by Composer)
            └── language/
                └── en-GB/
                    ├── en-GB.plg_system_spearstoneauth.ini
                    └── en-GB.plg_system_spearstoneauth.sys.ini

---

2. Installation Instructions

2.1. Setup and Packaging of the Extension

OPTIONAL: you can simply install the extension from the ZIP file provided in the release.

1. Prepare Composer Dependencies:

   • Navigate to plugins/system/spearstoneauth/ directory.
   • Ensure composer.json is present.
   • Run composer install.
   • This will create the vendor/ directory with dependencies.

2. Package the Extension:

   • Zip the contents of the spearstone_auth/ directory, not the directory itself.
   • The ZIP file must include:
     • spearstone_auth.xml package manifest.
     • administrator/ directory.
     • plugins/ directory.
     • LICENSEfile.

2.2. Installation

1. Log in to Joomla Administrator:

   • Access your Joomla site's backend (e.g., https://yourjoomlasite.com/administrator).

2. Install the Extension:

   • Navigate to Extensions > Manage > Install.

   • Under the Upload Package File tab, click Browse, select your ZIP file, and click Upload & Install.

3. Enable the System Plugin:

   • Go to Extensions > Plugins.

   • Search for Spearstone Auth.

   • Ensure the System - Spearstoneauth plugin is enabled.

---

3. Post-Installation Configuration

1. Access the Component Configuration:

   • Navigate to Components > Spearstone Auth.

2. Configure the Extension:

   • Extension Mode:

     • Choose from:
       • Disabled
       • Secondary to Joomla Frontend Auth
       • Primary Frontend Auth

   • OpenID Connect (OIDC) Identity Provider (IDP) Configuration:

     • Client ID: Enter your OIDC IDP client ID.
     • Client Secret: Enter your OIDC IDP client secret.
     • Authorization Endpoint: Enter the OIDC IDP authorization endpoint URL.
     • Token Endpoint: Enter the OIDC IDP token endpoint URL.
     • User Info Endpoint: Enter the oidc IDP user info endpoint URL (optional).
     • Redirect URI: Enter your Joomla site's URL that OIDC IDP will redirect to after authentication (should match the redirect URI registered in the OIDC IDP).
     • Scopes: Enter the scopes required (e.g., openid profile email).
     • Public Key: Paste the OIDC IDP public key in PEM format for verifying ID tokens.

   • Group Mapping:

     • Map IDP roles to Joomla group IDs.
     • For each role:
       • Role: The role name from the ID token.
       • Joomla Group: Select the Joomla user group to map to.

3. Save the Configuration:

   • Click Save & Close.

---

4. Testing the Extension

1. Test Authentication Flow:

   • Visit your Joomla site frontend.
   • Depending on the extension mode:
     • Secondary: Log out of Joomla if logged in.
     • Primary: Should redirect to your OIDC IDP for authentication.

2. Verify Group Assignments:

   • After authenticating with your OIDC IDP, ensure that access to content restricted to specific Joomla groups works as expected based on the role mappings.

3. Check Error Handling:

   • Test with invalid tokens or revoke access in your OIDC IDP to see how the extension handles failures.

---