PHPackages thathoff/kirby-oauth - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. thathoff/kirby-oauth ActiveKirby-plugin[Authentication & Authorization](/categories/authentication) thathoff/kirby-oauth ==================== Kirby OAuth 2 Plugin v3.5.0(3mo ago)3926.4k↓25.8%17[1 issues](https://github.com/thathoff/kirby-oauth/issues)[1 PRs](https://github.com/thathoff/kirby-oauth/pulls)MITPHPCI passing Since May 12Pushed 1mo ago3 watchersCompare [ Source](https://github.com/thathoff/kirby-oauth)[ Packagist](https://packagist.org/packages/thathoff/kirby-oauth)[ Docs](https://github.com/thathoff/kirby-oauth)[ RSS](/packages/thathoff-kirby-oauth/feed)WikiDiscussions main Synced today READMEChangelog (10)Dependencies (4)Versions (24)Used By (0) Kirby OAuth 2.0 Plugin ====================== [](#kirby-oauth-20-plugin) [![Screenshot of Kirby’s Login Screen with OAuth](/.github/screenshot.png?raw=true)](/.github/screenshot.png?raw=true) This plugin is an plugin to provide [OAuth 2.0](http://oauth.net/2/) support for panel authentication in [Kirby](https://getkirby.com). It uses the [PHP League’s OAuth 2 Client](https://oauth2-client.thephpleague.com/), so all [official](https://oauth2-client.thephpleague.com/providers/league/) and [third-party providers](https://oauth2-client.thephpleague.com/providers/thirdparty/) are supported. It’s even possible to [implement your own](https://oauth2-client.thephpleague.com/providers/implementing/). Kirby Compatibility ------------------- [](#kirby-compatibility) - For **Kirby 4 and up** use version 3.0.0 or higher - For **Kirby 3.6 - 3.9** use version 2 or higher - For **Kirby 3.0 - 3.6** use version 1 (not maintained anymore) --- Installation with Composer -------------------------- [](#installation-with-composer) Because of secondary dependencies for providers, **installation via composer is the only currently supported method**. ### Install the Plugin [](#install-the-plugin) ``` composer require thathoff/kirby-oauth ``` ### Install a Provider [](#install-a-provider) The Plugin uses [PHP League’s OAuth 2 Client](https://oauth2-client.thephpleague.com/) so you can select from all [official](https://oauth2-client.thephpleague.com/providers/league/) and [third-party providers](https://oauth2-client.thephpleague.com/providers/thirdparty/). It’s also possible to use your own provider by using the `GenericProvider` or [implement your own](https://oauth2-client.thephpleague.com/providers/implementing/) provider. For example to install support for Google run: ``` composer require league/oauth2-google ``` Options ------- [](#options) ### General Options [](#general-options) The following configuration options are available. And can be added to the Kirby `config.php`. ``` return [ 'thathoff.oauth' => [ // Add your providers configuration here 'providers' => [ // for details see „Provider Options” below ], // Only allow logins for existing kirby users (don’t create new users) 'onlyExistingUsers' => false, // Set the default role of newly created users. 'defaultRole' => 'admin', // Allow every valid user of all OAuth providers to login. // For details see “Configure Allowed Users” below. // DANGEROUS: Make sure you know what you’re doing when setting this to true! 'allowEveryone' => false, // List of E-mail domains which are allowed to login 'domainWhitelist' => [ // For details see “Configure Allowed Users” below. ], // List of E-mail addresses which are allowed to login 'emailWhitelist' => [ // For details see “Configure Allowed Users” below. ], // List of E-mail addresses which will get the admin role assigned 'adminWhitelist' => [ // For details see “Configure Allowed Users” below. ], // Remove the standard Kirby login form and only display OAuth options. 'onlyOauth' => false, // Automatically login with the first provider. This only works if `onlyOauth` is set to `true` and // only one provider is configured. 'autoRedirect' => false // Set this to 'true' to disable checking for the 'email_verified' field in the OAuth response. While some providers do not send this information, it is recommended that you keep this option enabled if your provider supports it. 'skipEmailVerifiedCheck' => false ], ]; ``` Important **Breaking change for Azure Active Directory users:** Previous versions automatically mapped the `upn` claim to the email and treated it as verified. This implicit behaviour has been removed for security reasons (a malicious or misconfigured provider could otherwise claim arbitrary identities via `upn`). If you use Azure AD, you now have to configure this explicitly per provider: ``` 'emailField' => 'upn', 'emailVerified' => true, ``` See the `emailField` / `emailVerified` options in the provider configuration below. ### Provider Options [](#provider-options) The `thathoff.oauth.providers` array is a list of all configured OAuth Providers with a unique key for each entry. Each array entry is used as the configuration option to a new OAuth Provider Class instance so all options which are documented for the selected OAuth Provider class are available. For example adding `'hostedDomain' => 'example.com'` in your google provider options will restrict users to an `@example.com` google account, as documented [here](https://github.com/thephpleague/oauth2-google). Additionally the two properties `name` and `class` are supported to supply a display name for the login screen and the Provider class to use when you don’t want to use the `GenericProvider`. ``` //... 'providers' => [ 'google' => [ 'class' => "League\OAuth2\Client\Provider\Google", // Use special google class from league/oauth2-google 'clientId' => 'somerandomstring.apps.googleusercontent.com', 'clientSecret' => 'clientsecret', 'hostedDomain' => 'example.com' // Restrict users to an `@example.com` google account (optional) 'icon' => 'users' // Pick any default Kirby icon for the login button (optional) 'theme' => 'green' // Pick any Kirby theme colors (see https://lab.getkirby.com/public/lab/components/buttons/2_themes) ], 'custom' => [ // this one uses \League\OAuth2\Client\Provider\GenericProvider automatically 'name' => 'My Custom Provider' // The name is optional 'clientId' => 'demoapp', // The client ID assigned to you by the provider 'clientSecret' => 'demopass', // The client password assigned to you by the provider 'redirectUri' => 'https://kirby.example.com/your-redirect-url/', 'urlAuthorize' => 'https://example.com/oauth2/lockdin/authorize', 'urlAccessToken' => 'https://example.com/oauth2/lockdin/token', 'urlResourceOwnerDetails' => 'https://example.com/oauth2/lockdin/resource', 'icon' => 'users', // Pick any default Kirby icon for the login button (optional) 'theme' => 'green' // Pick any Kirby theme colors (see https://lab.getkirby.com/public/lab/components/buttons/2_themes) 'scope' => 'openid email profile', //specify the scope passed form the OIDC provider to kirby 'emailField' => 'email', // Field in the provider's user data that contains the email address (default: "email"). Use "upn" for Azure AD. 'emailVerified' => null, // Override the email_verified claim: true treats the provider as always verifying emails, false as never. null (default) trusts the email_verified claim from the provider. ], ``` ### Redirect URL [](#redirect-url) OAuth providers require you to supply a **redirect URL** of your kirby instance when configuring an application. Please use `https://kirby.example.com/oauth/login/PROVIDER_ID` where kirby.example.com is your domain and PROVIDER\_ID is the key of the config option in config.php (in the previous config example `google` or `custom`). If you have installed Kirby in a subdirectory, remember to include the subdirectory in the URL. ### Configure Allowed Users [](#configure-allowed-users) By default only whitelisted users are allowed to login into the Kirby panel. **Domain Whitelist:** By adding domains to the domain whitelist (`domainWhitelist`) all accounts with a verified email address at one of the domains are permitted. **Email Whitelist:** By adding email addresses to the email whitelist (`emailWhitelist`) all accounts with a verified email address matching one of the entires are permitted. **Admin Whitelist:** By adding email addresses to the admin whitelist (`adminWhitelist`) all accounts with a verified email address matching one of the entires are getting the admin role assigned. **Allow Everyone:** By setting `allowEveryone` to `true` all authenticated accounts are able to login. *Please use this option with care!* You probably want to change the default user role to a more restricted one then the default `admin`. **Default Role:** Newly created users get the role defined with `defaultRole` when they first login. The default is `admin`. Please note that when the user has ben created already the role will not be updated. You can set this role to `nobody` if you want to manually whitelist users by changing the role in the Kirby panel. **Only Existing User:** By setting `onlyExistingUsers` to true only created uses are able to login with an OAuth provider, no new users are created. ### Use Hooks [](#use-hooks) Before and after the KirbyUser gets created or logged in a hook is triggered. ``` /** * @var \League\OAuth2\Client\Provider\ResourceOwnerInterface $oauthUser * @var Kirby\Cms\User $user */ 'hooks' => [ 'thathoff.oauth.user-create:before' => function ($oauthUser) { // return null|true to use the plugins user-creation // return a Kirby\Cms\User to overwrite the plugin user creation }, 'thathoff.oauth.user-create:after' => function ($oauthUser, $user) { }, 'thathoff.oauth.login:before' => function ($oauthUser, $user) { }, 'thathoff.oauth.login:after' => function ($oauthUser, $user) { } ] ``` ### Health Score 57 — FairBetter than 98% of packages Maintenance84 Actively maintained with recent releases Popularity41 Moderate usage in the ecosystem Community22 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 82.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~131 days Recently: every ~56 days Total 20 Last Release 115d ago Major Versions v0.2.0 → v1.0.02019-05-13 v1.2.2 → v2.0.02022-01-23 2.0.2 → 3.0.02024-01-10 ### Community Maintainers ![](https://www.gravatar.com/avatar/e313f1ec98c211100e91b929b574203dc78572be0812d1c4015881d33e2c3fe7?d=identicon)[markusdenhoff](/maintainers/markusdenhoff) --- Top Contributors [![thathoff](https://avatars.githubusercontent.com/u/797760?v=4)](https://github.com/thathoff "thathoff (67 commits)")[![pReya](https://avatars.githubusercontent.com/u/4677417?v=4)](https://github.com/pReya "pReya (3 commits)")[![PaulRaschke](https://avatars.githubusercontent.com/u/28190977?v=4)](https://github.com/PaulRaschke "PaulRaschke (2 commits)")[![ieteo](https://avatars.githubusercontent.com/u/98889739?v=4)](https://github.com/ieteo "ieteo (1 commits)")[![jonathan-reisdorf](https://avatars.githubusercontent.com/u/8958624?v=4)](https://github.com/jonathan-reisdorf "jonathan-reisdorf (1 commits)")[![ladenree](https://avatars.githubusercontent.com/u/988602?v=4)](https://github.com/ladenree "ladenree (1 commits)")[![pwaldhauer](https://avatars.githubusercontent.com/u/432323?v=4)](https://github.com/pwaldhauer "pwaldhauer (1 commits)")[![robertschnuell](https://avatars.githubusercontent.com/u/19629717?v=4)](https://github.com/robertschnuell "robertschnuell (1 commits)")[![danielbuechele](https://avatars.githubusercontent.com/u/685740?v=4)](https://github.com/danielbuechele "danielbuechele (1 commits)")[![TinQ0](https://avatars.githubusercontent.com/u/41490684?v=4)](https://github.com/TinQ0 "TinQ0 (1 commits)")[![fabianmichael](https://avatars.githubusercontent.com/u/395617?v=4)](https://github.com/fabianmichael "fabianmichael (1 commits)")[![flokuek](https://avatars.githubusercontent.com/u/11317959?v=4)](https://github.com/flokuek "flokuek (1 commits)") --- Tags kirbykirby-pluginkirby4kirby5kirby5-pluginoauthoauth2 ### Embed Badge ![Health badge](/badges/thathoff-kirby-oauth/health.svg) ``` [![Health](https://phpackages.com/badges/thathoff-kirby-oauth/health.svg)](https://phpackages.com/packages/thathoff-kirby-oauth) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k34.4k15](/packages/tempest-framework)[thenetworg/oauth2-azure Azure Active Directory OAuth 2.0 Client Provider for The PHP League OAuth2-Client 25310.7M83](/packages/thenetworg-oauth2-azure)[league/oauth2-google Google OAuth 2.0 Client Provider for The PHP League OAuth2-Client 42223.4M176](/packages/league-oauth2-google)[stevenmaguire/oauth2-keycloak Keycloak OAuth 2.0 Client Provider for The PHP League OAuth2-Client 2306.4M45](/packages/stevenmaguire-oauth2-keycloak)[getkirby/cms The Kirby core 1.5k584.8k473](/packages/getkirby-cms)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 751291.4k43](/packages/civicrm-civicrm-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)