openid_connect_16x16.pngAllow an XWiki instance to authenticate on an OpenID Connect provider
Recommended
TypeJAR
CategoryAuthenticator
Developed by

Thomas Mortagne

Active Installs101
Rating
Rate!
1 Votes
LicenseGNU Lesser General Public License 2.1
Installable with the Extension Manager

Description

Allow an XWiki instance to authenticate on an OpenId Connect provider. It also automatically synch

See also OpenID Connect Provider.

oidc_client_provider.png

Release notes can be found on OpenID Connect project page.

Main limitations

Configuration

Configuration Guides for specific systems

Lemon LDAP / Open PAAS

A configuration guide is available to connect XWiki to LemonLDAP / OpenPAAS using the OpenIDC XWiki client.

xwiki.cfg

#-# The authentication management class.
xwiki.authentication.authclass=org.xwiki.contrib.oidc.auth.OIDCAuthServiceImpl

xwiki.properties

#-# The OpenId Connect base URL of the XWiki instance to use as provider.
#-# See following endpoints properties if the provider is not an XWiki instance.
#-# If not indicated, it will be asked to the user.
# oidc.xwikiprovider=https://xwikiorg-node1.xwikisas.com/xwiki/oidc

#-# The generic OpenId Connect endpoints to use to communicate with the provider.
#-# Not needed in case of XWiki based provider.
# oidc.endpoint.authorization=https://xwikiorg-node1.xwikisas.com/xwiki/oidc/authorization
# oidc.endpoint.token=https://xwikiorg-node1.xwikisas.com/xwiki/oidc/token
# oidc.endpoint.userinfo=https://xwikiorg-node1.xwikisas.com/xwiki/oidc/userinfo

#-# The method used to access the userinfo endpoint.
#-# 
#-# Supported values are:
#-# * GET: use GET HTTP method
#-# * POST: use POST HTTP method
#-# 
#-# The default is:
# oidc.endpoint.userinfo.method=GET

#-# The pattern to use to generate the XWiki user name.
#-# 
#-# The following variables are available:
#-# oidc.user.subject: the unique id of the user in the provider
#-# oidc.user.mail: the mail of the user
#-# oidc.user.familyName : the last name of the user
#-# oidc.user.givenName: the first name of the user
#-# oidc.user.preferredUsername: the recommended string to use as id for the user
#-# oidc.provider: the URL of the XWiki provider (only when a XWiki provider is used)
#-# oidc.provider.host: the host of the provider URL
#-# oidc.provider.path: the path of the provider URL
#-# oidc.provider.protocol: the protocol (usually https) of the provider URL
#-# oidc.provider.port: the port of the provider URL
#-# oidc.issuer: the issuer URI
#-# oidc.issuer.host: the host of the issuer URI
#-# oidc.issuer.path: the path of the issuer URI
#-# oidc.issuer.scheme: the scheme (usually https) of the issuer URI
#-# oidc.issuer.port: the port of the issuer URI
#-#
#-# The following suffixes can be used:
#-# * ".lowerCase": the lower case version of the string
#-# * ".upperCase": the upper case version of the string 
#-# * ".clean": a version of the string stripped from ".", ":", ",", "@", "^" characters and "\s" (all forms of white spaces).
#-#             It can itself be suffixed with ".lowerCase" and ".uperCase".
#-# 
#-# The default is: 
# oidc.user.nameFormater=${oidc.issuer.host.clean}-${oidc.user.preferredUsername.clean}

#-# The pattern to use to generate the unique identifier of the user in the OpenId Connect provider.
#-# It is used to avoid collisions with user have similar name.
#-# 
#-# The syntax is the same than the one described for oidc.user.nameFormater property.
#-# 
#-# The default is: 
# oidc.user.subjectFormater=${oidc.user.subject}

#-# The OpenID Connect client identifier used by the authenticator.
#-#
#-# The default is the automatically generated unique id of the XWiki instance.
# oidc.idtokenclaims=xwiki_instance_id

#-# The name of the claim used to get the list of group the user belong to
#-# 
#-# The default is:
# oidc.groups.claim=xwiki_groups

#-# The custom claims to request to the provider for the UserInfo
#-# 
#-# The available custom claims are:
#-# xwiki_groups (or whatever you indicated in oidc.groups.claim): the groups a user belong to in the provider (see "Group synchronization" section for more details)
#-# xwiki_user_<fieldname>: the suffix to use to request any field in the user profile document (generally when the provider is XWiki) 
#-# The default is:
# oidc.userinfoclaims=xwiki_user_accessibility,xwiki_user_company,xwiki_user_displayHiddenDocuments,xwiki_user_editor,xwiki_user_usertype

#-# The time after which the user information should be refreshed (in milliseconds)
#-# 
#-# The default is:
# oidc.userinforefreshrate=600000

#-# The client identifier used by the authentication.
#-# The default is the identifier of the XWiki instance.
# oidc.clientid=

#-# The client secret (optionally) registered on the provider.
#-# By default nothing is sent to the provider.
# oidc.secret=

#-# How to send the client id and secret.
#-# 
#-# Supported values are:
#-# * client_secret_basic: the id and the secret are sent using BASIC auth header
#-# * client_secret_post: the id and the secret are sent in the the request body 
#-# 
#-# The default is:
# oidc.endpoint.token.auth_method=client_secret_basic

#-# Receiving a groups list is enough to enable group synchronization but you might need to configure XWiki groups names different from the remote groups names.
#-# 
# oidc.groups.mapping=MyXWikiGroup=my-oidc-group
# oidc.groups.mapping=MyXWikiGroup2=my-oidc-group2
# oidc.groups.mapping=MyXWikiGroup2=my-oidc-group3

#-# The groups the user need to belong to be allowed to authenticate.
#-# Not taken into account if not set or empty.
#-# 
# oidc.groups.allowed=

#-# If the user belong to one of these groups it won't be allowed to authenticate
#-# 
# oidc.groups.forbidden=

#-# Disable the OpenId Connect authenticator
#-# 
#-# The default is:
# oidc.skipped=false

Bypass OpenID Connect

As indicated in the previous section you can disable OpenID Connect using the property oidc.skipped in the xwiki.properties file.

It's also possible to skip OpenId Connect temporarily using a URL parameter: for example https://mydomain/xwiki/bin/view/Main/?oidc.skipped=true.

Group synchronization

The default group synchronization is enabled by adding the claim xwiki_groups to the property oidc.userinfoclaims in the xwiki.properties file.

This synchronization expect to receive the list of group names (without the `wiki:XWiki.` prefix) in which the user should should be placed (groups are automatically created when they don't exist).

It's also possible to implement your own custom group synchronization in a listener. See Listeners section.

Customization

Templates

The authenticator use a template to ask the user for the target provider when it's not provided in the configuration. This template can be overwritten trough the standard template system.

The name of the template is oidc/client/provider.vm.

Listeners

It's possible to implement an event listener and be notified during user profile update to add more to this process or do other things after it:

  • org.xwiki.contrib.oidc.event.OIDCUserUpdating to modify the user profile before it being saved
  • org.xwiki.contrib.oidc.event.OIDCUserUpdated to do something after the user profile has been saved

Troubleshooting

Enable DEBUG log

See Logging.

The specific packages to track for OpenID Connect module is org.xwiki.contrib.oidc. There is several ways to enable debug log.

With the Logging Admin UI

Use Logging Admin UI from the Administration section, add set TRACE or DEBUG level classes located in package org.xwiki.contrib.oidc.

Anything you set trough the Logging Administration won't be remembered after a restart.

With the Logback configuration file

You need to add the following in WEB-INF/classes/logback.xml:

<!-- LDAP debugging -->
<logger name="org.xwiki.contrib.oidc" level="trace"/>

You need to restart XWiki for this to be taken into account.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


Once you installed the extension you will need to indicate you want to use it as authenticator with the property xwiki.authentication.authclass in xwiki.cfg file. See Configuration section for more details.

Dependencies

Dependencies for this extension (org.xwiki.contrib.oidc:oidc-authenticator 1.15):

Tags:
Created by Thomas Mortagne on 2016/05/27 16:29
    

Get Connected