Skip to main content

Integration

Integrating OpenProject with External Systems​

This document provides guidelines on how to integrate OpenProject with various external systems, enhancing its capabilities and facilitating seamless collaboration across different platforms. Below are step-by-step instructions for commonly required integrations including version control systems, authentication services, and email services.

Overview​

Integrating OpenProject with external services can greatly expand its functionality. Here are some of the most common integrations:

  1. Version Control Systems (VCS)

  • Git

  • Subversion (SVN)

  1. Authentication Providers

  • LDAP/Active Directory

  • SAML

  • OAuth2

  1. Email Services
  • SMTP for outgoing emails

Pre-requisites​

  • Administrative access to your OpenProject installation.

  • Appropriate access credentials for each external service (e.g., API keys, user access credentials).

  • Necessary network access from the OpenProject server to the external services.

Step 1: Version Control System Integration​

Git Integration​

  1. Install Git on the OpenProject Server:

bashCopy code
sudo apt-get install git
  1. Configure Git Repositories in OpenProject:

  • Navigate to Administration > Repositories in OpenProject.

  • Choose New repository and select Git.

  • Enter the path to your Git repository and any authentication details if needed.

Subversion Integration​

  1. Install Subversion on the OpenProject Server:

bashCopy code
sudo apt-get install subversion
  1. Configure SVN Repositories in OpenProject:

  • Navigate to Administration > Repositories.

  • Choose New repository and select Subversion.

  • Provide the URL to your SVN repository and necessary authentication details.

Step 2: Authentication Provider Integration​

LDAP/Active Directory​

  1. Navigate to LDAP Authentication:
  • Go to Administration > LDAP Authentication.
  1. Add New LDAP Authentication:

  • Click on New LDAP Authentication and fill in the LDAP details:

  • Name: Descriptive name for the LDAP connection.

  • Host: LDAP server IP or hostname.

  • Port: Typically 389 for LDAP or 636 for LDAPS.

  • Account and Password: LDAP credentials if required.

  • Base DN: The base DN for your LDAP searches.

  • Filter: Any specific filter to apply.

SAML Authentication​

  1. Install Required Plugins:
  • Ensure the OpenProject SAML plugin is installed and activated.
  1. Configure SAML Settings:

  • Navigate to Administration > SAML Authentication.

  • Input SAML details like IdP entity id, SSO URL, SLO URL, and certificate data.

OAuth2 Provider Integration​

  1. Setup OAuth2:

  • Similar to SAML, install any necessary plugins and navigate to the OAuth2 configuration under Administration.

  • Configure the client ID, client secret, site, and token URL according to your OAuth provider’s documentation.

Step 3: Email Configuration​

SMTP Setup​

  1. Configure Outgoing Emails:

  • Navigate to Administration > Settings > Email notifications.

  • Select SMTP under the Email delivery method.

  • Fill in SMTP details including address, port, authentication method, username, and password.

Testing and Validation​

  • Version Control Integration: Test by committing to a repository and verifying that OpenProject reflects the changes.

  • Authentication Integration: Test by logging in with credentials managed by the authentication provider.

  • Email Integration: Test by triggering an email event in OpenProject (e.g., issue creation or user invitation).

Troubleshooting​

  • Verify all network connections, credentials, and configurations if any integration fails.

  • Consult the logs in OpenProject (log/production.log) for error messages that can provide insights into any issues