oAuth Plugin

Compatible with DokuWiki

2024-02-06 "Kaos" yes
2023-04-04 "Jack Jackrum" yes
2022-07-31 "Igor" yes
2020-07-29 "Hogfather" yes

Allow users to login through various oAuth1 and oAuth2 compatible authentication providers. Requires additional plugins.

Last updated on: 2024-11-02
Provides: Auth, Action
Repository: Source

Similar to authgoogle, evesso, fedauth, sfauth

Tagged with authentication, oauth

Needed for oauthauthsch, oauthazure, oauthcognito, oauthdiscord, oauthdrkserver, oauthfacebook, oauthgeneric, oauthgithub, oauthgoogle, oauthkeycloak, oauthosm, oauthwechange

By Andreas Gohr

The initial development of this plugin has been sponsored by Linuxhotel.

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

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.

Configuration

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.

In addition the oauth plugin has a few global options that will apply to all provider plugins.

`custom-redirectURI`	You can this to override the autodetected Redirect URI. Unless you know what you're doing you probably don't want to set anything here.
`mailRestriction`	Only users that have an email ending in the domain set here will be able to authenticate. Must start with an `@`
`singleService`	Login with single oAuth service only (disables local logins!)
`register-on-auth`	Register authenticated users even if self-registration is disabled in main configuration. Otherwise an admin needs to create a local user first before they can login via oAuth
`overwrite-groups`	Overwrite all DokuWiki user groups by those supplied by provider

User Management

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 authplain to 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.

Each logged in user is added automatically to group of the name of the service, f.e azure:

auth.php:139

Development

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.

Service

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. \dokuwiki\plugin\yourplugin.

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 AUTHORIZATION_METHOD_* constants

Adapter

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.

An adapter is a DokuWiki action plugin. However you don't need to implement most action plugin basics but instead can simply inherit from \dokuwiki\plugin\oauth\Adapter.

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 action.php.

The methods you want to override here are

getUser() – use $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 user, name, mail and grps.
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 oauthidp for 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 (facebook) or the fully qualified class name of the service class you implemented
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)

Additionals

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 key and secret entry. Refer to development manual on plugin development for more info

Change Log

Version upped (2024-11-02 23:51)
Merge pull request #155 from YoitoFes/add_respbody_to_excp (2024-11-02 18:49)
Add http response body to HttpTokenResponseException (2024-11-02 15:16)
Version upped (2024-10-31 23:51)
Merge pull request #154 from YoitoFes/add_exception (2024-10-31 09:11)
Add HttpTokenResponseException making error handling easy (2024-10-31 02:26)
Merge pull request #150 from dokuwiki-translate/lang_update_915_17226… (2024-08-05 13:39)
translation update (2024-08-03 01:50)

Table of Contents