DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:oauth

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
plugin:oauth [2016-06-29 12:41] 2001:700:1:109:b42a:f0d4:ce67:1555plugin:oauth [2024-03-05 23:51] (current) – version upped andi
Line 2: Line 2:
  
 ---- plugin ---- ---- plugin ----
-description: Allow users to login through various oAuth1 and oAuth2 compatible authentication providers+description: Allow users to login through various oAuth1 and oAuth2 compatible authentication providers. Requires additional plugins.
 author     : Andreas Gohr  author     : Andreas Gohr 
 email      : dokuwiki@cosmocode.de email      : dokuwiki@cosmocode.de
 type       : auth, action type       : auth, action
-lastupdate : 2016-06-21 +lastupdate : 2024-03-05 
-compatible : HrunDetritus+compatible : GreeboHogfather, Igor, Jack Jackrum, Kaos
 depends    :  depends    : 
 conflicts  conflicts 
Line 21: Line 21:
 ---- ----
  
-[[http://www.linuxhotel.de/|{{ http://www.linuxhotel.de/pics/logo-2008-250.png?150|sponsored by Linuxhotel}}]] +[[http://www.linuxhotel.de/|{{ https://www.linuxhotel.de/wp-content/themes/liho/img/linuxhotel.svg?150&recache|sponsored by Linuxhotel}}]] 
-The development of this plugin has been sponsored by [[http://www.linuxhotel.de/|Linuxhotel]].+The initial development of this plugin has been sponsored by [[http://www.linuxhotel.de/|Linuxhotel]].
  
 ===== Installation ===== ===== Installation =====
-[[http://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ http://cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]] 
  
-Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.+[[https://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ https://www.cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]] 
 + 
 +Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually
 + 
 +Install and configure an oAuth plugin for your auth provider, e.g. [[plugin:oauthgoogle]].
  
 After setup, you have to select ''oauth'' in the [[config:authtype]] config option. After setup, you have to select ''oauth'' in the [[config:authtype]] config option.
  
-==== 2014-05-05a Ponder Stibbons release ====+:!: 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]].
  
-:!: Please note: this plugin requires two small bugfixes in the Ponder Stibbons release:+If you need the older version of this plugin, download [[https://github.com/cosmocode/dokuwiki-plugin-oauth/archive/refs/tags/2020-06-14.zip|version 2020-06-14]].
  
-  * [[github>49cd1ed0c3598adf2be1b42e09281137eb41cc2b]] 
-  * [[github>5aca1d54db0f056fec97a36487b09ebf0a864ed3]] 
  
 ===== Configuration ===== ===== Configuration =====
  
-The plugin currently supports the following auth providers:+The plugin requires installation of additional auth provider plugins. Currently only a few of them are available:
  
-  * Facebook +  * [[plugin:oauthgoogle|Google oAuth]] 
-  * Google+ +  * [[plugin:oauthfacebook|Facebook oAuth]] 
-  * Yahoo +  * [[plugin:oauthgithub|Github oAuth]] 
-  * Github +  * [[plugin:oauthcognito|Amazon Cognito oAuth]] 
-  * Auth0 +  * [[plugin:oauthazure|Microsoft Azure oAuth]] 
-  * Dataporten+  * [[plugin:oauthgeneric|Generic oAuth]] 
 +  * [[plugin:oauthkeycloak|Keycloak oAuth]] 
 +  * [[plugin:oauthwechange|WECHANGE oAuth]]
  
-More can easily be added (see [[#development]] section below)+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. The URLs to those are linked in the configuration manager.+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: The setup of these "Applications" differs between the different providers, but there are a few things you generally need to provide to create one:
Line 62: Line 65:
 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. 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.
  
-==== Google specific ====+In addition the oauth plugin has a few global options that will apply to all provider plugins.
  
-Do not forget to fill informations into "APIs & auth / Consent screen"If you don'tthe client authentification request will display "Error, no application name".+| ''custom-redirectURI'' | You can this to override the autodetected Redirect URIUnless you know what you're doing you probably don'want to set anything here. | 
 +| ''mailRestriction'' | Only users that have an email ending in the domain set here will be able to authenticateMust 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 |
  
  
Line 74: Line 81:
  
 {{ :plugin:oauthprofile.png?200|oAuth service association in user profile}} {{ :plugin:oauthprofile.png?200|oAuth service association in user profile}}
 +
 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). 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. 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.
  
-Please note: this plugin will never support login via Twitter because Twitter doesn't give access to the user's email address.+Each logged in user is added automatically to group of the name of the service, f.e ''azure'': 
 +  * [[https://github.com/cosmocode/dokuwiki-plugin-oauth/blob/05d29310ce98af896825bca44d3cab16d9aab92f/auth.php#L139|auth.php:139]]
  
 ===== Development ===== ===== Development =====
  
-This plugin comes with a few predefined services. In the backend it uses the [[https://github.com/Lusitanian/PHPoAuthLib|Lusitanian PHPoAuthLib]] which supports many more services. However each service needs it's own Adapter class which implements the specific API calls to request user data over an oAuth authenticated connection.+Support for new Identity Providers (IdP) can be added by creating new plugins. To implement authentication with a new Identity Provider, two classes are neededservice and an adapter.
  
-Pull Requests for implementing more public services are welcome!+Have a look at [[https://github.com/cosmocode/dokuwiki-plugin-oauthdoorkeeper|Implementation for Doorkeeper]] to get an idea about what is needed.
  
-This plugin can easily integrate with your own service. A "Generic" backend class allows for easy configuration of endpoints. However the actual API call for fetching user data still needs to be implemented. The plugin comes with an example Adapter class called "Doorkeeper" which implements oAuth against the [[https://doorkeeper-provider.herokuapp.com|demo setup]] of the Ruby oAuth library [[https://github.com/doorkeeper-gem/doorkeeper|Doorkeeper]].+==== Service ====
  
-To implement your own service, simply copy the Doorkeeper class and adjust the implementation and add the right config values to your config.+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
  
-=== Change Log ===+If the [[https://github.com/Lusitanian/PHPoAuthLib|Lusitanian PHPoAuthLib]] already includes a service class for your IdP you don't need to implement it yourself.
  
-{{rss>https://github.com/cosmocode/dokuwiki-plugin-oauth/commits/master.atom date}}+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 [[https://github.com/cosmocode/dokuwiki-plugin-oauth/blob/master/vendor/lusitanian/oauth/src/OAuth/Common/Service/ServiceInterface.php|\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 [[https://github.com/cosmocode/dokuwiki-plugin-oauth/blob/master/Service/AbstractOAuth2Base.php|\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 [[devel:action_plugins|action plugin]]. However you don't need to implement most action plugin basics but instead can simply inherit from [[https://github.com/cosmocode/dokuwiki-plugin-oauth/blob/master/Adapter.php|\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 ''oauth//idp//'' 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|development manual]] on plugin development for more info 
 +
 +
 +===== Change Log =====
 +
 +{{rss>https://github.com/cosmocode/dokuwiki-plugin-oauth/commits/master.atom date}}
  
plugin/oauth.1467196868.txt.gz · Last modified: 2016-06-29 12:41 by 2001:700:1:109:b42a:f0d4:ce67:1555

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki