This is an old revision of the document!
Table of Contents
Compatible with DokuWiki
- 2022-07-31 "Igor" unknown
- 2020-07-29 "Hogfather" yes
- 2018-04-22 "Greebo" yes
- 2017-02-19 "Frusterick Manners" unknown
The initial development of this plugin has been sponsored by Linuxhotel.
Install and configure an oAuth plugin for your auth provider, e.g. oauthgoogle.
After setup, you have to select
oauth in the authtype config option.
As of 2021-12-15 this plugin provides only an oAuth framework, particular services are no longer bundled. To actually be able to use it you have to install and configure at least one of the auth provider plugins listed below under configuration.
If you need the older version of this plugin, download version 2020-06-14.
The plugin requires installation of additional auth provider plugins. Currently only a few of them are available:
More can easily be created (see development section below)
To be able to use one of those providers you need to create an “Application” at the authentication provider's developer website. Refer to the individual auth provider plugins for details.
The setup of these “Applications” differs between the different providers, but there are a few things you generally need to provide to create one:
- a name (eg. “DokuWiki login”)
- a redirect or callback URI - the value you need to provide here can be seen in the config manager
- sometimes you need to select the type of data an application may access. Here you need to make sure email addresses and user names are allowed
- often you can add more info like a company logo, description and so on
Once the application is set up it will display a “key” and a “secret”. These have to be set up in the configuration manager. Once done the service can be used for login.
This plugin sits on top of the usual authplain authentication mechanism. Password based logins will continue to work and users can still register directly at your wiki, unless you configure it otherwise.
However, the plugin introduces one limitation: email addresses have to be unique for each user. When you're switching from
oauth make sure existing users have unique email addresses!
When a new user logs in through one of the configured oAuth providers a standard user entry is created and associated with the oAuth provider. Additional providers can be enabled in the user's profile (Associations are simple group memberships).
Users can login through any of the services enabled in their profile - for that to work, their email address configured in DokuWiki must match with the primary address known to the service.
Support for new Identity Providers (IdP) can be added by creating new plugins. To implement authentication with a new Identity Provider, two classes are needed: a service and an adapter.
Have a look at Implementation for Doorkeeper to get an idea about what is needed.
The service implements all the specifics for the actual oAuth communication with the IdP. That includes setting the endpoint URLs and configuring the authorization mechanisms.
If the Lusitanian PHPoAuthLib already includes a service class for your IdP you don't need to implement it yourself.
If no service file exists for your IdP your plugin needs implement it. The class needs to be in your plugin's namespace eg.
Ultimately the Service needs to implement a \OAuth\Common\Service\ServiceInterface, but you are more likely to start off an existing base class.
For an oAuth 2 based IdP you probably want to inherent from \dokuwiki\plugin\oauth\Service\AbstractOAuth2Base.
You most probably want to override the following methods:
getAuthorizationEndpoint()– return the URL where the oAuth workflow is started
getAccessTokenEndpoint()– return the URL where an Access or Refresh Token can be requested
getAuthorizationMethod()– One of the
The adapter implements all meta info needed for the work with DokuWiki and most importantly how to fetch user data once an oAuth authorization happened.
Because the adapter is an action plugin component, it needs to follow the specific naming scheme for plugins. Eg. the class needs to be named
action_plugin_yourplugin without a namespace and has to be located in a file named
The methods you want to override here are
$this→getOAuthService()to access the authorized service and use it's
request()method to fetch the user's data. Return an array with the keys
getScopes()– an array with scopes to request, if any
getLabel()– The display name to use for your IdP
getServiceID()– if you follow the namingscheme of
oauthidpfor your plugin you don't need to implement this, otherwise return a identifier (it will also used for the associated group)
registerServiceClass()– return either the name of a Lusitania provided service (
getColor()– a hex color to use on the login button. use your IdPs primary color here
logout()– do the procedures required on logout, if any (available as of 2021-12-19)
You should provide a simple SVG icon to be used on the login button. Place it as
logo.svg into your plugin.
Provide config and translations for at least a
secret entry. Refer to development manual on plugin development for more info
- Merge pull request #129 from dokuwiki-translate/lang_update_427_16500… (2022-05-04 14:38)
- translation update (2022-04-15 08:55)
- Version upped (2022-03-28 23:51)
- Merge pull request #125 from cosmocode/update-user (2022-03-28 11:45)
- Keep user groups set by different OAuth adapter plugins (2022-03-28 11:38)
- Smarter merge of user groups (2022-03-24 12:59)
- Update local user data with info from provider (2022-03-23 12:56)
- Merge pull request #120 from dokuwiki-translate/lang_update_374_16427… (2022-02-17 08:10)