XWiki and OpenProject integration: what it does and how it connects
The OpenProject Integration extension displays OpenProject work packages as lists, cards or single items inside XWiki pages, and it can create work packages from XWiki. The two systems are linked through an OAuth application that is configured on both sides, so the wiki can read and write tasks in OpenProject on behalf of the signed-in setup. For a team whose specifications and meeting notes live in XWiki while its tasks live in OpenProject, this lets a project page carry a live task view next to the documentation it relates to.
The integration is an extension listed in the XWiki Store as Pro, so it is not part of the free XWiki Standard distribution. Before planning the rollout, confirm the license terms that apply to your deployment with XWiki SAS, including whether your existing subscription tier covers the extension and which support it includes. Check the extension page in the XWiki Store for the XWiki versions it supports. The setup requires XWiki 14.10 or above, so an older wiki will need an upgrade first. OpenProject itself is licensed under GPL-3.0, but you should still confirm which OpenProject edition your team needs for the work package features you plan to display.
The connection is built in two steps. In OpenProject's administration, an administrator creates an OAuth application with a redirect URI that points to the XWiki callback. In XWiki, an administrator then enters the OpenProject server URL, the client ID and the client secret. Both steps have to agree exactly, including the scheme, host and path, so write the redirect URI down once and copy it from the same source each time. The OpenProject server must be reachable from the XWiki server over HTTPS, and the XWiki server must be reachable from the browser for the callback to complete. Test the connection from a page before you give any readers access.
Two decisions shape the design more than the setup itself. The first is whose permissions a page uses when it reads or creates work packages: confirm with XWiki SAS and by testing with accounts of different roles whether requests run as each signed-in user or under a shared account, because that decision controls what a reader can see on a page. The second is where each view belongs, since a list suits a project overview, cards suit a sprint or status page, and a single item suits a decision record. Plan for the client secret to be rotated and stored in your secrets process, and add a check to your upgrade plan so that OpenProject and XWiki version changes are tested against the extension before they reach production.
What you need running before you configure the OAuth link
Setup connects XWiki and OpenProject through an OAuth application, so both systems need a supported version, a hosting decision, a working network path, secure transport and an administrator before anything is configured. The cards list these prerequisites in the order teams usually check them. Work through them on both systems before you open the XWiki extension settings.
XWiki 14.10 or later
The OAuth setup described for the OpenProject Integration requires XWiki 14.10 or above, so confirm the version on the instance that will hold the integration before you start. Check the release in the administration area, and plan any upgrade ahead of the work, since the extension is installed into that instance. If you run an older release, decide whether to upgrade first or wait for a later maintenance window. Confirm the extension version against your XWiki release using the XWiki Store listing.
An OpenProject instance you administer
Your team needs an OpenProject instance it can administer, because the OAuth application is created in OpenProject's administration area and its client secret must be rotated by people who can access that area. OpenProject supports Docker-based installation (the option its documentation recommends), .deb and .rpm packages for 64-bit Linux, and Kubernetes with Helm charts for horizontal scaling. Packaged installs support Ubuntu 22.04, Debian 12, CentOS or RHEL 9.x and SUSE Linux Enterprise Server 15. Confirm your platform against the current system requirements before installation.
PostgreSQL 16 with required extensions
OpenProject 16.0.0 and later officially support PostgreSQL 16 or later and require the pg_trgm, btree_gist and unaccent extensions. Check the database version, and confirm that the account OpenProject uses can create or enable these extensions before the installer runs. If a database team or a managed cloud service owns the database, ask them to confirm extension availability early, since a missing extension blocks installation. For releases before 16.0.0, follow the database requirements in that release's own documentation.
Server URLs both sides can reach
XWiki must reach the OpenProject server URL to call its API, and users' browsers must reach both systems to complete the sign-in redirect. Settle the public hostnames before you create the OAuth application, because the redirect URI points to the XWiki callback and the server URL is entered in XWiki afterward. Check firewall rules, DNS records and reverse proxy path rules in both directions. Test from the XWiki server itself, since its network segment often differs from a workstation's view.
HTTPS between the two systems
Serve both XWiki and OpenProject over HTTPS so that the authorization code exchange and the token requests do not send client secrets or tokens in plain text. Decide which certificate authority issues the certificates, and confirm that the XWiki server trusts it, since a certificate error on the callback breaks sign-in in ways that are hard to diagnose from the user side. Verify that any reverse proxy in front of each system forwards the original scheme and host name. Record which hostnames carry certificates and when they expire.
Administrator accounts on each side
You need an administrator account on XWiki to install the extension and enter the server URL, client ID and client secret, and an administrator account in OpenProject to create the OAuth application. Use named accounts so the change history shows who created or rotated the credentials. Confirm that the OpenProject administrator can see the work packages the wiki readers will view, since OpenProject permissions still decide what appears in each list, card and single view.
How the XWiki and OpenProject integration shows list, card and single views
The OpenProject Integration for XWiki gives wiki editors three ways to show work packages on a page: as a list, as cards, or as a single item. According to the XWiki Store listing, the same extension also offers charts, calendar views and filters, so a page can show a status overview next to a dated schedule without anyone copying data out of OpenProject. Before you plan page layouts, confirm with the extension documentation which views and chart types your installed version provides, because the set of options is what determines how much content editors can build without developer help. Editors place these views by inserting the extension's elements into a wiki page and configuring each one. The XWiki Store page is the authoritative reference for the exact syntax, parameters and filter fields, so check it before you write editor guidance for your team. Do not assume the names of macros or parameters from another XWiki extension, since the integration may use different names. A practical first step is to build one test page per view on a staging XWiki, then record the working configuration so your editors have tested examples to copy. Each view reads work packages live from OpenProject when the page loads. Nothing is copied into XWiki, so the data a reader sees depends on the OpenProject account that the connection uses. Because the integration authenticates through the OAuth application you configured, the returned work packages follow that account's OpenProject permissions. Decide early which account the wiki connects with, and confirm whether pages show each reader's own permissions or the connected account's permissions. These two models produce very different results, and the choice affects what your security reviewers will expect to see. When the connected account lacks access to a project or work package, the view should omit those items rather than expose them. Confirm the exact behavior in a test: create a work package in a restricted project, load a page with each view using an account without access, and check what appears, including counts, chart totals and calendar entries, since aggregated figures can reveal information even when individual items are hidden. Also test what a reader sees when the OpenProject server is unreachable or the OAuth token has expired, and make sure the error message does not expose server details. Record these results as part of your acceptance tests.
How to connect XWiki to OpenProject in six steps
This sequence links XWiki to OpenProject through an OAuth application, so wiki pages can display and create work packages under each user's own OpenProject permissions. Each step ends with a check that tells you whether the connection is ready to test.
Confirm versions and prerequisites
The platform owner confirms that the XWiki instance runs version 14.10 or above and that OpenProject is reachable over HTTPS from the browsers of the people who will use the integration. Confirm the XWiki version in the administration area and the OpenProject version in its administration information. Create a test project in OpenProject and a non-administrator test account with access to it. Done means both platforms are on supported versions, the URLs resolve from user networks, and the test project and account exist.
Create the OAuth application in OpenProject
An OpenProject administrator opens the OAuth application section of the administration area and registers a new application for XWiki. Set the redirect URI to the XWiki callback address, built from your XWiki base URL and the callback path given in the OpenProject Integration documentation. Confirm that the scheme, host, port, path and any trailing slash match the XWiki address exactly, because a single difference will stop the authorization from completing. Done means the application appears in the list with the expected redirect URI.
Record the client ID and secret
The administrator copies the client ID and client secret that OpenProject generates for the new application. Store them in your organization's approved secrets store, not in a wiki page, ticket or chat message, and limit who can read them. If OpenProject shows the secret only once, record it before closing the dialog and regenerate it if it is lost. Done means both values are stored in the secrets store and the person who will configure XWiki can retrieve them.
Install the OpenProject Integration extension
A XWiki administrator installs the OpenProject Integration extension from the XWiki Store, which lists it as a Pro extension, so confirm that your subscription covers it before installation. Use the extension manager on a staging instance first if you have one. Check whether the installed version is compatible with your XWiki version and whether a restart is required in your environment. Done means the extension appears as installed in the extension manager and its administration settings page is accessible to the administrator.
Enter the server URL, client ID and secret
The XWiki administrator opens the OpenProject Integration settings and enters the OpenProject server URL, the client ID and the client secret from step three. Use the same base URL that users open in their browsers, so the authorization redirect returns to a matching address. Save the settings, then complete the authorization flow for the test account. Done means the settings save without errors, the redirect goes to OpenProject, and the authorization returns the user to XWiki with the connection marked as active.
Test list and create with a non-administrator account
Sign in to XWiki as the non-administrator test account and create a test page with the work package display macro, filtered to the test project. Confirm that the list loads and shows only the work packages that account can see in OpenProject. Then create a work package from XWiki and confirm that it appears in the OpenProject project. Repeat the list view with an account that has no access to the project to confirm it shows nothing. Done means the list loads for the authorized account, the create action produces a work package in OpenProject, and the restricted account sees no items.
Which OpenProject fields and permissions appear in XWiki
This table maps the OpenProject objects a connected XWiki page can show or create to the view where they appear and the OpenProject permission that governs them. Use the confirm column as your checklist for the extension documentation before you design pages, since view options and filter syntax vary by extension version. The main takeaway is that OpenProject roles, not XWiki groups, decide what each connected user can read or change.
| OpenProject object | Where it appears in XWiki | Governing permission | Confirm with extension documentation |
|---|---|---|---|
| Work packages (subject, ID, description) | List, card and single item views | Role permission to view work packages in the project | Which fields appear by default in card versus list views, and whether custom fields can be added |
| Project membership and project scope | Filtered result sets by project | Project membership and the role assigned to the connected user | How project filters are written, and whether a filter can span several projects at once |
| Status | Status shown on items and usable as a filter | Role permission to view work packages, with status transitions governed separately | Whether status is displayed as text, color or both, and whether it can be filtered on |
| Assignee | Assignee field on items and in filters | Visibility of the user and project membership of that user | Whether assignee filters match the connected user automatically, and how unassigned items are handled |
| Dates (start, due) | Date fields in lists, cards and calendar views | Role permission to view work packages in the project | Which date fields are exposed, and how the calendar view handles items with no dates |
| Work package type (task, bug, milestone) | Type label, and type filters where supported | Role permission to view work packages in the project | Whether types can be filtered and whether milestones render differently from tasks |
| Creating work packages from XWiki | Create action on a page, for users who are allowed to add work | Role permission to add work packages in the target project | Which project and type are preselected, and which required fields the form asks for |
| Access by XWiki group | Not applicable as a permission source | OpenProject roles only, not XWiki groups | Confirm that page-level XWiki rights do not extend what the connected OpenProject user can see |
Keeping project documentation next to project tracking
Decide before the first page is written which system is authoritative for status. In an XWiki and OpenProject setup, the wiki should hold the content that changes slowly and needs narrative: specifications, decisions, architecture notes and runbooks. OpenProject should hold the work packages, their status, assignees, dates and comments. Once that split is agreed and written down, most duplication problems stop before they start, because nobody has to ask which copy of a status is correct. Set the status rule in writing. For each kind of information, name the system that owns it. A reasonable starting rule is that work package status, assignee and due date live only in OpenProject, and that wiki pages never restate them as plain text. If a decision page needs to say a feature is "in progress," it should point to the work package instead of typing the word. Ask the project leads to confirm the rule with their teams, and review it again after the first release cycle, when the gaps will be visible.
Give each project a fixed page structure in XWiki, mirrored by a project structure in OpenProject. A typical outline for illustrative purposes might include a project home page, a specifications space, a decisions log, a runbooks space and a meeting notes area. Each page should have a named owner who is responsible for accuracy, not for writing every word. Ownership should be recorded on the page itself, and the team should agree on who can approve changes to specifications and who can retire a runbook. Owners often change during a project, so the page should name a role where possible, such as the product owner or the service owner, alongside the person.
When a page refers to a work package, link to it rather than copying its details. A link is stable, shows current status and keeps the reader in the source of truth. An embedded live view, created with the OpenProject Integration, is better for summary pages such as a release overview or a list of open risks, where the reader needs a current picture across many items. Use embedded views sparingly, because a page full of live lists becomes hard to read and slow to scan. Confirm in your test environment how the views behave with the permissions of the reader, since a viewer without access to OpenProject should not see content they cannot open there.
Review the page structure and linking rule after a pilot project. Check whether any page has become a second tracker, whether owners are still reachable, and whether links point to closed or moved work packages. Ask the implementation partner to include this review in the handover, and agree who maintains the rule after launch.
Securing the XWiki and OpenProject integration OAuth client
Connecting XWiki to OpenProject creates a trust relationship between two systems, and the OAuth client is the weakest point if it is set up casually. The cards cover the stored secret, the people who can change settings, transport, redirect matching, the account the wiki uses, grant cleanup on departure and the licensing decision for Enterprise identity features.
Protect the client secret
The OpenProject OAuth client secret is stored in the XWiki OpenProject Integration configuration, so anyone who can read that configuration can use it. Confirm that the secret does not appear in page content, exported XAR packages, logs or screenshots, and that only server administrators can read the stored value. Restrict editing of the extension settings to a small group of wiki administrators, because changing the server URL or client ID can redirect XWiki to another system. Rotate the secret after any suspected exposure and update both systems at the same time.
Enforce HTTPS on both servers
The XWiki server and the OpenProject server must both serve their pages and the OAuth token exchange over HTTPS, because the client secret and access tokens travel between them. Check that the server URL configured in XWiki uses https, that OpenProject's host and protocol settings match its public address, and that certificates are valid and trusted by the XWiki runtime. Plain HTTP on either side exposes tokens to anyone on the network path.
Pin the redirect URI
The OAuth application in OpenProject should accept one redirect URI: the exact XWiki callback path, using the same scheme, host and port that users reach. Wildcards or extra callback entries allow an authorization code to be sent to a location you did not configure. Copy the callback value from the setup instructions for your XWiki version, and after any change to the XWiki hostname, update the OpenProject entry before users sign in again.
Use a dedicated integration account
Create a separate OpenProject user for the integration and grant it only the project roles needed to view and create work packages in the projects the wiki will display. Do not reuse a personal administrator account, because the OAuth grant then carries that person's full access. Document which projects the account can reach and confirm the role set with each project owner before go-live.
Review grants when people leave
Each user who connects XWiki to OpenProject creates an OAuth grant tied to their account. When someone leaves the organization, disable their OpenProject account, check which grants and tokens remain, and revoke any that belong to that person. Add this step to the offboarding checklist for both the wiki and project teams, and confirm with your administrators how the connector behaves when a grant is revoked.
Decide on Enterprise identity features
OpenProject's pricing page lists single sign-on (SAML, OIDC, CAS, Kerberos, Okta) and LDAP group synchronization as Enterprise features. Decide before the build starts whether your organization needs them, for example if wiki and project sign-in must follow the same directory groups, because adding them changes licensing and the identity design. If they are not needed, keep the OAuth client design and record the decision with the reason.
Why work packages fail to load after setup
This table lists the failures teams most often hit after connecting XWiki to OpenProject, with the likely cause and fix for each. Work through the rows in order when work packages do not load, since the first three usually trace back to setup values. The main takeaway is that an OpenProject upgrade can break a working connection, so it needs a check before the wiki side changes.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch | The OAuth application in OpenProject registers a callback URL that differs from the XWiki callback in scheme, host, port or path. | Copy the XWiki callback URL exactly into the OpenProject OAuth application, save, then retry the connection. |
| Wrong or rotated client secret | The secret was pasted incorrectly, or it was regenerated in OpenProject administration without updating XWiki. | Update the secret in the XWiki settings and confirm the client ID belongs to the same OAuth application. |
| XWiki version below 14.10 | The OpenProject Integration requires XWiki 14.10 or above, and older installs fail during setup or on first load. | Check the running version in XWiki administration before installing, and upgrade the wiki first if it is older. |
| Server URL unreachable or mixed HTTP and HTTPS | The configured server URL uses a different scheme than the site, or the XWiki server cannot resolve or reach the OpenProject host. | Use one scheme end to end and the URL the XWiki server can reach. Test the address from the XWiki host before saving. |
| Connected account lacks project permissions | The user who authorized the connection has no view rights on the projects or work packages being requested. | Check that account's role in each project. Test with a named user who has the access readers will have. |
| OpenProject upgrade changes API or OAuth behavior | A new OpenProject release can change API endpoints or OAuth handling that the wiki extension depends on. | Stage the OpenProject upgrade, test work package lists, cards and single views, then update production. |
| Release notes not checked before wiki changes | The OpenProject side changed, but the wiki side was not reviewed against that release's notes. | Check each OpenProject release notes before upgrading, and confirm the extension version your team tests against. |
Questions buyers ask before hiring help with the integration
Does OpenProject Community cost anything for this integration?
The OpenProject Community edition is free to use, and it includes work packages, Gantt charts, agile boards, time tracking and dashboards, with community support. The Community edition does not include vendor support, so your team relies on public channels and its own staff when something breaks. The XWiki OpenProject Integration is listed in the XWiki Store as a Pro extension, so its license terms, and whether it fits your user count, need confirmation in writing before purchase. Your remaining costs are internal staff time for administration and testing, hosting for both systems, and the implementation work, which is quoted from a written scope. If you need vendor-backed support on the OpenProject side, the Enterprise tiers are the next option to review.
How much does OpenProject Enterprise cost per user?
OpenProject Enterprise on-premises is priced per named user per month, according to OpenProject's published pricing. Basic is listed at 5.95 euros per user per month, Professional at 10.95 euros with a 25-user minimum, and Premium at 15.95 euros with a 100-user minimum. Corporate is quoted on request for 250 or more users. Enterprise also adds single sign-on options such as SAML, OIDC, CAS, Kerberos and Okta, LDAP group synchronization and custom branding. Your total depends on the number of named users you license, the tier your required features need, and whether a minimum applies to you. Confirm current list prices on the pricing page before budgeting, because published prices can change. Enterprise is a separate purchase from the integration work.
What does XWiki consulting cost per day?
XWiki SAS lists consulting at 1200 EUR per day, and that rate requires a Business or Enterprise support plan. The support plan is a recurring cost, and its price depends on the tier and user count, so confirm it directly with XWiki SAS. XWiki Pro and support subscriptions come in Starter, Basic, Business and Enterprise tiers, and the company states that cloud and on-premises pricing is the same. Whether you need XWiki consulting days at all depends on who carries which tasks. If DeployOpen handles the OAuth setup, view configuration and testing under a written scope, you may not need to buy XWiki consulting for the same work. Ask for a written split of tasks by party, with the cost of each.
How long does the OpenProject integration take to set up?
The duration depends on the scope agreed in writing, and DeployOpen does not state a duration before a scoped plan exists. The main drivers are the number of OpenProject projects that need wiki views, the number of page templates for project documentation, the complexity of the permission model in both systems, and how much testing you require before users see the result. A single project with a few standard pages is a much smaller job than a portfolio with role-specific views and formal sign-off testing. Ask for a plan that lists each project, template and permission group, the test cases, and the points where your team must review or approve. The schedule should follow from that plan.
What do we need to provide before the integration work starts?
You need to provide access and decisions as well as a server. On the XWiki side, you need version 14.10 or above, administrator rights, and permission to install the extension. On the OpenProject side, you need an administrator who can create an OAuth application, plus a stable server URL and a network path between the XWiki server and OpenProject. Confirm which install method OpenProject runs on, because the system requirements differ by packaging and hosting model. Also provide a list of the projects in scope, the people who approve page templates, your permission model, and a small group of test users from each role. Settle who may see which projects early so that it does not delay the build.
Can our own team set up the XWiki OpenProject integration alone?
Your team can attempt the setup alone if it has administrators for both platforms and someone who can test permissions carefully. The core setup follows a documented sequence: create an OAuth application in OpenProject with a redirect URI to the XWiki callback, then add the server URL, client ID and secret in XWiki. The harder work is designing the list, card and single views, the page templates and the permissions so that readers see only what they should, and then testing that across roles. Ask whether your team has the time to build and verify those pieces, who will maintain them after upgrades, and who will respond when a release of either product changes behavior. You can keep all of this in-house, or buy a fixed-scope engagement for some parts and keep the rest.
What costs should we confirm in writing before approving the project?
Confirm every cost line in writing, because the integration has several separate payers. Your team's time for administration, testing and approval is an internal cost you should estimate yourself. The OpenProject edition is either free Community use or a per-user Enterprise subscription. XWiki consulting, XWiki support plans and the OpenProject Integration extension each carry their own terms, so ask for the extension's license terms and confirmation that it covers your user count. Hosting for both systems is a recurring cost in your infrastructure. The implementation fee should follow from the written scope. For each item, ask whether it is one-time or recurring, what drives its price, and who invoices it.
How DeployOpen scopes, delivers and supports this integration
DeployOpen plans, builds, documents and supports the XWiki and OpenProject integration inside infrastructure you control, so project documentation in XWiki sits next to work packages in OpenProject. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Confirm the XWiki version and OpenProject version you run, since the connector requires XWiki 14.10 or above.
- Agree which views are in scope: lists, cards or single work package items on specific XWiki pages.
- Define who creates work packages from XWiki and which OpenProject projects and roles they map to.
- Document the OAuth application setup on both sides, including redirect URIs and secret handling.
How we build
- Install and configure the XWiki OpenProject Integration extension and verify it against your XWiki release.
- Create the OAuth application in OpenProject administration and connect the server URL, client ID and secret in XWiki.
- Build the page templates for list, card and single work package views, with filters you agreed during scoping.
- Test read and create paths with user accounts holding different OpenProject permissions, and record the results.
How we hand over
- Deliver a written configuration record covering both OAuth applications, URLs, redirect URIs and where secrets are stored.
- Provide runbooks for adding projects, rotating the OAuth secret and reviewing which users can create work packages.
- Walk through the page templates and filters with the people who will maintain project pages after handover.
- Confirm acceptance tests against the written scope before the engagement closes.
How we support
- Plan a review of the integration when you upgrade XWiki or OpenProject, since both products release on their own schedules.
- Offer ongoing support, upgrades and testing as a retainer after handover if your team wants continued coverage.
- Agree in the scope how incidents and change requests are raised, with the people responsible on each side named.
- Ask for a quote that separates one-time setup from any recurring support, so the ongoing cost is visible.
