Install with Composer 

Install the extension via Composer:

composer req oliverkroener/ok-azure-login

After installation, update the database schema to create the configuration table:

vendor/bin/typo3 database:updateschema

See also t3start:installing-extensions.

Include the static TypoScript 

1. In the TYPO3 backend, go to the Template module
2. Select the root page of your site
3. Choose Info/Modify and click Edit the whole template record
4. Switch to the Includes tab
5. Add Azure Login from the list of available static templates

Add the content elements 

The extension provides two content elements, available under the Azure Login group in the New Content Element Wizard:

Azure Login

Renders a "Sign in with Microsoft" button. When a user authenticates via Microsoft Entra ID, the extension matches their email to an existing fe_users record and logs them in.

Azure Logout

Renders a "Sign out" button for logged-in users. Can optionally redirect to the Microsoft logout endpoint to sign the user out of Microsoft as well.

To add them:

1. Go to the Page module and select the page where the login or logout button should appear
2. Click Create new content element
3. Select from the Azure Login group: either Azure Login or Azure Logout
4. Configure the element settings (button theme, redirect URL, etc.)
5. Save and clear caches

Backend login 

The extension automatically registers a backend login provider. Once configured (see Configuration), one or more "Sign in with Microsoft" buttons appear as a separate tab on the TYPO3 backend login screen at /typo3/.

To set up backend login:

1. Go to Web > Azure Login and switch to the Backend tab
2. Click Add Backend Login Configuration
3. Fill in the Azure credentials (Tenant ID, Client ID, Client Secret, Label)
4. Copy the auto-generated Redirect URI and register it in your Azure app
5. Save the configuration

The backend redirect URI (/typo3/azure-login/callback) is automatically derived from the TYPO3 route configuration. You can create multiple backend login configurations for different Azure tenants.

Backend module (recommended) 

The recommended way to configure Azure credentials is via the dedicated backend module. This allows you to manage credentials per TYPO3 site, so each site can use its own Azure app registration. The module also supports multiple backend login configurations, each appearing as a separate login button on the TYPO3 backend login screen.

1. Open the backend module

   In the TYPO3 backend, navigate to Web > Azure Login.

2. Select a page in the page tree

   Click on any page that belongs to the site you want to configure. The module automatically resolves the site root page from the TYPO3 Site Configuration.

3. Choose Frontend or Backend tab

   The module has two tabs:

   • Frontend -- configure Azure credentials for frontend user login on this site
   • Backend -- manage backend login configurations (list, create, edit, delete)

Extension settings (fallback) 

As a fallback, global credentials can be configured via Extension Configuration in the TYPO3 backend (Admin Tools > Settings > Extension Configuration > ok_azure_login).

These global settings are used when no per-site database configuration exists for the current site. This is useful for simple single-site installations or as a migration path from older versions of the extension.

The following settings are available:

Configuration resolution order 

The extension resolves Azure credentials differently for frontend and backend:

Frontend login:

1. Database configuration for the current site root page (from the backend module)
2. Extension Configuration (global fallback)

Backend login:

1. Configuration by UID (if a specific config was selected)
2. Database configuration for the current site root page
3. Global backend configuration (site_root_page_id = 0)
4. Extension Configuration (global fallback)

If a database record exists but has an empty Tenant ID, it is treated as unconfigured and the extension falls back to the next source.

TypoScript configuration 

The extension registers a static TypoScript template Azure Login that configures the Fluid template paths. Include it via the Template module (see Installation).

You can override the template paths via TypoScript constants:

plugin.tx_okazurelogin_login {
    view {
        templateRootPath = EXT:your_sitepackage/Resources/Private/Extensions/OkAzureLogin/Templates/
        partialRootPath = EXT:your_sitepackage/Resources/Private/Extensions/OkAzureLogin/Partials/
        layoutRootPath = EXT:your_sitepackage/Resources/Private/Extensions/OkAzureLogin/Layouts/
    }
}

Content element settings 

Azure Login (frontend login)

Button Theme

Choose between a dark or light Microsoft button style.

Azure Logout (frontend logout)

Button Theme

Choose between a dark or light Microsoft button style.

Microsoft Sign-Out

When enabled, the user is redirected to the Microsoft logout endpoint to sign them out of Microsoft as well as TYPO3.

Redirect URL

Custom URL to redirect to after logout. Defaults to the site root.

How it works 

The authentication flow is handled entirely by the extension:

1. The content element renders a "Sign in with Microsoft" button linking to the Microsoft Entra ID authorization endpoint.
2. The user authenticates at Microsoft and is redirected back with an authorization code.
3. A PSR-15 middleware intercepts the callback, exchanges the code for user information via the Microsoft Graph API, and injects the user data into the TYPO3 authentication chain.
4. The TYPO3 authentication service looks up the user by email in the appropriate user table (fe_users or be_users).
5. If a matching, non-disabled user is found, they are logged in and redirected to the return URL.
6. For frontend login: if no matching user is found and auto-create is enabled, a disabled fe_users record is created. The user sees a message that their account is pending activation.
7. For backend login: if no matching user is found, the user is redirected back to the login page with an error message.

Security notes 

• Encrypted secrets: Client secrets stored via the backend module are encrypted at rest using PHP Sodium (sodium_crypto_secretbox). The encryption key is derived from TYPO3's encryptionKey.
• HMAC-signed state: The OAuth state parameter is HMAC-signed using TYPO3's encryptionKey and has a 10-minute TTL to prevent CSRF and replay attacks.
• Per-site isolation: Each TYPO3 site can have its own Azure credentials, preventing credential leakage across multi-site installations.
• SameSite cookie handling: The middleware preserves session cookies on the OAuth callback redirect and downgrades SameSite=Strict to SameSite=Lax to ensure the browser sends cookies after the cross-site redirect from Microsoft.
• Stale parameter stripping: The middleware removes stale azure_login_error and azure_login_success query parameters from the return URL before appending the current result, preventing parameter accumulation on retries.
• Never commit client secrets to version control.
• Use separate Azure app registrations for development, staging, and production.
• Rotate client secrets regularly before their expiration date.

Report Issues