grim/reviewboard_jetbrains_hub

Add a readme

2020-06-16, Gary Kramlich
e3bcdfdcc999
Parents a8ca9429612b
Children a563f97f4da4
Add a readme
3 files changed, 80 insertions(+), 0 deletions(-)
  • +80 -0
    README.md
  • +0 -0
    images/admin_extension.png
  • +0 -0
    images/admin_settings_authentication.png
    • --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/README.md Tue Jun 16 23:34:41 2020 -0500
    @@ -0,0 +1,80 @@
    +# Review Board Jetbrains Hub
    +
    +This is a plugin for [Review Board](https://reviewboard.org) that allows you to
    +use [Jet Brains Hub](https://jetbrains.com/hub) as an authentication source.
    +
    +Since Review Board 3 does not yet support OAuth2 for authentication, this uses
    +the Resource Owner Password Credentials OAuth2 flow in Hub. This means that
    +users will use their normal JetBrains Hub username and password to login. This
    +also means that two factor authentication methods are not supported and users
    +with 2FA on will need to create an application password in their Hub settings.
    +
    +# Prerequisites
    +
    +To setup this plugin you will of course need both Review Board and JetBrains
    +Hub up and running.
    +
    +## Review Board
    +
    +You can find the official documentation for installing Review Board
    +[here](https://www.reviewboard.org/docs/manual/3.0/admin/).
    +
    +## JetBrains Hub
    +
    +You can find documentation for installing JetBrains Hub
    +[here](https://www.jetbrains.com/help/hub/installation-and-upgrade.html).
    +
    +Once JetBrains Hub is up and running, you'll need to create a Service for
    +Review Board. A service in JetBrains Hub's terms is another service that is
    +using JetBrains Hub for authentication. You can find documentation on creating
    +JetBrains Hub services in the
    +[official documentation](https://www.jetbrains.com/help/hub/add-service.html).
    +
    +# Installation
    +
    +Installation should be done via:
    +
    +```
    +pip install rbjbhub
    +```
    +
    +Once the plugin is installed, just make sure to rescan for extension in Review
    +Board and you should be able to enable it.
    +
    +![review board admin extensions page with the plugin enabled](images/admin_extension.png)
    +
    +Once you have enabled the extension, head over to the Authentication settings
    +and configure the plugin to match your settings from JetBrains Hub.
    +
    +![review board admin settings authentication page](images/admin_settings_authentication.png)
    +
    +All of these settings should be the values of the service you created in
    +JetBrains Hub above, with the exception that value for `Scope` is the ID of the
    +Hub service in your JetBrains Hub instance, which in my experience has always
    +been `0-0-0-0-0`.
    +
    +When you're all done, go ahead and save your settings. Then try to login as a
    +user that exists in your JetBrains Hub instance. If you're able to log in, you
    +are good to go!
    +
    +# Caveats
    +
    +User email addresses are **ONLY** set, if the email address has been verified
    +in JetBrains Hub.
    +
    +User information is **ONLY** synchronized when a user logs in. This means that
    +if a user has changed their email address in Hub and are added to a review
    +request before they log into Review Board, the user will not receive an email
    +for that review request.
    +
    +If a user has 2FA turned on, they will have to use an application password to
    +login.
    +
    +If a user changes their username in JetBrains Hub a new Review Board account
    +will be created for them on their next login. To avoid this, they should have
    +a Review Board administrator change their username in Review Board.
    +
    +If a user already existed before logging in with JetBrains Hub, they will still
    +be able to login via that password. As a Review Board administrator you can
    +change this password to something that the user does not know.
    +
    Binary file images/admin_extension.png has changed
    Binary file images/admin_settings_authentication.png has changed