Top Menu

Jump to content
Home
    • Projects
    • Work packages
    • News
    • Getting started
    • Introduction video
      Welcome to OpenProject Community
      Get a quick overview of project management and team collaboration with OpenProject. You can restart this video from the help menu.

    • Help and support
    • User guides
    • Videos
    • Shortcuts
    • Community forum
    • Professional support

    • Additional resources
    • Data privacy and security policy
    • Digital accessibility (DE)
    • OpenProject website
    • Security alerts / Newsletter
    • OpenProject blog
    • Release notes
    • Report a bug
    • Development roadmap
    • Add and edit translations
    • API documentation
  • Sign in
      Forgot your password?
      Create a new account

      or sign in with your existing account

      Google

Side Menu

  • Overview
  • Activity
  • Roadmap
  • Work packages
  • Calendars
  • Team planners
  • Boards
  • Forums
  • Wiki
    • Table of contents
      • Expanded. Click to collapseCollapsed. Click to showDeveloper
        • Hierarchy leafAccessibility Checklist
        • Hierarchy leafCode Review Guidelines
        • Expanded. Click to collapseCollapsed. Click to showContribution
          • Hierarchy leafGit Workflow
          • Hierarchy leafTranslations
        • Expanded. Click to collapseCollapsed. Click to showDeveloping Plugins
          • Hierarchy leafDeveloping an OmniAuth Authentication Plugin
        • Hierarchy leafRelease Process
        • Hierarchy leafReport a bug
        • Hierarchy leafSecurity
        • Hierarchy leafSetting up an OpenLDAP server for testing
        • Hierarchy leafTheme Features
      • Hierarchy leafDownload
      • Expanded. Click to collapseCollapsed. Click to showFeature tour
        • Hierarchy leafRelease Notes OpenProject 30
        • Expanded. Click to collapseCollapsed. Click to showRelease Notes OpenProject 30 - Overview
          • Hierarchy leafGlossary
          • Hierarchy leafRelease Notes - Accessibility
          • Hierarchy leafRelease Notes - Accessibility changes
          • Hierarchy leafRelease Notes - Add work package queries as menu items to sidebar
          • Hierarchy leafRelease Notes - Copy projects based on Templates
          • Hierarchy leafRelease Notes - Design changes
          • Hierarchy leafRelease Notes - Fixed Bugs
          • Hierarchy leafRelease Notes - Keyboard Shortcuts
          • Hierarchy leafRelease Notes - Project settings
          • Hierarchy leafRelease Notes - Ruby&Rails Update
          • Hierarchy leafRelease Notes - Security
          • Hierarchy leafRelease Notes - Timelines
          • Hierarchy leafRelease Notes - Work packages
      • Hierarchy leafHowto create animated gifs
      • Hierarchy leafMigration Squashing
      • Hierarchy leafMod security
      • Hierarchy leafNew work package page
      • Hierarchy leafOP3 to OP4 Debian upgrade
      • Hierarchy leafOP4 Ubuntu1404 Stable with MySQL in production
      • Hierarchy leafOpenProject 40 Development Setup
      • Expanded. Click to collapseCollapsed. Click to showOpenProject Foundation
        • Hierarchy leafBoards
        • Hierarchy leafMembers
        • Hierarchy leafOPF-Meetings
        • Hierarchy leafStatutes
      • Expanded. Click to collapseCollapsed. Click to showRelease Notes
        • Hierarchy leafOpenProject released on Bitnami
      • Expanded. Click to collapseCollapsed. Click to showRelease Notes OpenProject 40 - Overview
        • Hierarchy leafRelease Notes OpenProject 40 - Accessibility improvements
        • Hierarchy leafRelease Notes OpenProject 40 - Column header functions in work package table
        • Hierarchy leafRelease Notes OpenProject 40 - Improved Design
        • Hierarchy leafRelease Notes OpenProject 40 - Integrated query title on work package page
        • Hierarchy leafRelease Notes OpenProject 40 - Integrated toolbar on work package page
        • Hierarchy leafRelease Notes OpenProject 40 - OmniAuth integration for OpenProject
        • Hierarchy leafRelease Notes OpenProject 40 - Work package details pane
      • Expanded. Click to collapseCollapsed. Click to showSecurity and privacy
        • Hierarchy leafFAQ
      • Expanded. Click to collapseCollapsed. Click to showSupport
        • Expanded. Click to collapseCollapsed. Click to showDownload and Installation
          • Hierarchy leafInstallation MacOS
          • Expanded. Click to collapseCollapsed. Click to showInstallation OpenProject 3 0
            • Hierarchy leafDebian Stable with MySQL in production
            • Hierarchy leafInstallation Ubuntu
            • Hierarchy leafInstallation Windows
            • Hierarchy leafInstallation on Centos 65 x64 with Apache and PostgreSQL 93
          • Expanded. Click to collapseCollapsed. Click to showInstallation OpenProject 40
            • Hierarchy leafOP4 Debian Stable with MySQL in production
          • Expanded. Click to collapseCollapsed. Click to showMigration paths
            • Hierarchy leafFrom Chilliproject to OpenProject
            • Hierarchy leafMigration 15 to 30
            • Hierarchy leafMigration 24 to 30
            • Hierarchy leafMigration Redmine 2x › OpenProject 30
            • Hierarchy leafOpenProject 3 Migration
          • Hierarchy leafOpenProject 40
        • Expanded. Click to collapseCollapsed. Click to showNews
          • Hierarchy leafNew OpenProject Translations Plugin
          • Hierarchy leafNew Plugin on OpenProjectorg Local Avatars
          • Hierarchy leafNew design for OpenProject
          • Hierarchy leafNews Accessibility workshop for OpenProject
          • Hierarchy leafNews Glossary for OpenProject
          • Hierarchy leafNews Heartbleed fixed
          • Hierarchy leafNews Icon Fonts
          • Hierarchy leafNews OpenProject 30 Release
          • Hierarchy leafNews Release GitHub Integration Plugin
          • Hierarchy leafNews Success Story Deutsche Telekom
          • Hierarchy leafNews Timelines
          • Hierarchy leafOpenProject 3013 released
          • Hierarchy leafOpenProject 3017 released
          • Hierarchy leafOpenProject 40 released
          • Hierarchy leafOpenProject 40 will be coming soon
          • Hierarchy leafOpenProject 405 released
          • Hierarchy leafOpenProject and pkgrio
          • Hierarchy leafOpenProject news moved to a new blog
          • Hierarchy leafOpenProjectBitnami
          • Hierarchy leafPackager version with plugins released ("Community edition")
          • Hierarchy leafRegistration OpenProject-Foundation
          • Hierarchy leafRelease OpenProject AuthPlugins
          • Hierarchy leafUpdates on OpenProject
          • Hierarchy leafWe need your feedback for the the new fullscreen view for work packages
        • Hierarchy leafOpenProject Plug-Ins
      • Hierarchy leafWiki
You are here:
  • Developer
  • Developing Plugins
  • Developing an OmniAuth Authentication Plugin

Content

Developing an OmniAuth Authentication Plugin

  • More
    • Print
    • Table of contents

OmniAuth

The OpenProject core integrates OmniAuth. This means that OmniAuth providers can be used to authenticate OpenProject users. For the time being this is not possible for existing users but only for new users who register using that particular provider.

This page describes how to create an OpenProject plugin to authenticate users via an Omniauth strategy.

Warning

This howto is in a preliminary state and explains a low-level way to create an OmniAuth authentication plugin for OpenProject. We will provide a more high-level API and update this howto soon.

OpenID Connect

There is a bare minimum plugin implementing a mock strategy for OpenProject using the provided OmniAuth infrastructure. You can refer to this plugin and compare to see how things can be done.

Terminology

Strategy

An OmniAuth strategy implements a certain way of authentication. Examples for this are LDAP, OAuth and OpenID Connect strategies.

Provider

An OmniAuth provider uses an OmniAuth strategy in order to authenticate a user against a certain service.
For instance there can be two providers that both use the OpenID Connect strategy but for different services.

To do

Any authentication plugin has to do at least the following things:

  1. Create plugin settings (e.g. for server-side secrets) if necessary
  2. Register its authentication provider(s) with OmniAuth
  3. Render a sign-in link for each provider on the login page and the login drop down menu

Authentication Plugin How-to

In the following section we will go through the basic steps required to create an authentication plugin for OpenProject.

Generate a plugin

First off you can use the plugin generator to create a basic plugin to base yours on.
How to do that is described here. In short it’s the following commnad:

# in OpenProject directory
rails generate open_project:plugin my_auth_plugin path/to/where/you/want/to/have/it

Let’s assume that the plugin you generated is called openproject-my_auth_plugin.

Implement the strategy

This is specific to your plugin. There may already be a gem implementing a strategy for the service you want to use.
In that case you can skip this step and use an existing gem. Just google ‘omniauth ’ and chances are that you will find one.
E.g. for twitter ‘omniauth twitter’ will lead you to this quickly.

Register required settings

If you want to use settings for your plugin in order to configure your authentication provider you will have to register them in lib/open_project/my_auth_plugin/engine.rb by adding them to the already generated plugin registration call like this:

register 'openproject-my_auth_plugin',
  :author_url => 'Hans Wurst',
  :requires_openproject => '>= 3.1.0',
  :settings => { 'default' => { 'auth_server_address' => {'192.168.178.42'} } }

You can access your plugin’s settings like this:

server_addr = Setting.plugin_openproject_my_auth_plugin["auth_server_address"]

Register the provider(s)

For this you can use the openproject-auth_plugins plugin, which provides you with an easy way to integrate a new authentication plugin into OpenProject.
As described in the plugin’s readme file you just add the following bit to the class body of Engine:

register_auth_providers do
  strategy :my_auth_plugin_strategy do
    [
      {
        name: 'my_provider',
        display_name: 'Optional Label', # (optional) provider's name as shown in OpenProject
        icon: 'my_auth_plugin/optional_provider_icon.png', # (optional) provider icon
        # example options depending on your strategy:
        host: Setting.plugin_openproject_my_auth_plugin["auth_server_address"]
      }
    ]
  end
end

OmniAuth will try to look up a strategy based on the passed symbol :my_auth_plugin_strategy, meaning that in this case it would expect a strategy class to be defined as follows:

module OmniAuth
  module Strategies
    class MyAuthPluginStrategy
      # ...

You can register any number of providers using different strategies (or the same) with different options.
For instance you could configure two OpenID Connect providers using the same strategy (OpenIDConnect) but with different options according to the service to be used (e.g. Google vs Microsoft).

Add your plugin to Gemfile.plugins

All that’s that left to do is declaring your plugin in the file Gemfile.plugins in your OpenProject application’s root directory.
If you haven’t published it as a gem yet you can also use a local copy:

  gem "openproject-auth_plugins", :git => 'https://github.com/opf/openproject-auth_plugins.git', :branch => 'dev'
  gem 'openproject-my_auth_plugin', :path => 'plugins/openproject-my_auth_plugin'

Also don’t forget to include the openproject-auth_plugins as a dependency in your plugin’s gem specification (openproject-my_auth_plugin.gemspec).
The first line in the snippet shown above is only necessary because the openproject-auth_plugins plugin itself has not been published as a gem yet.

Profit

That’s it. Now users can authenticate using your own provider.

Loading...