Overview

FeatureHub comes with a built in identity system, which stores passwords in a securely salted fashion. It is fine to use if you don’t wish to federate your identity, and works well in small organisations. You do not need to configure anything to use the built in identity system, it is there by default.

However you may wish to federate your identity. FeatureHub lets you support both the internal system, or an external identity system (or several) as well as providing you the ability to turn off your internal system completely. You can migrate from one to the other as it will simply match email addresses. e.g. If you configure a user in the system using the identity foo@bar.com and then federate bar.com to an OAuth provider, the user will remain the same in the system, you do not need to recreate or delete the user.

Further, you can configure the system to disallow attempts at logging in to your FeatureHub instances if their user hasn’t already been created. This allows you to expose FeatureHub to your organisation’s IDP, but not let everyone from that IDP in.

it is important to note that FeatureHub does not use the Access Token it receives from the OAuth provider to call back, it simply follows the standard OAuth2 Authorization Code Flow and requests an openid style token. This contains the email address and username and FeatureHub will then drop the token. No further callbacks are made.

Generalised Config

auth.disable-login=false
auth.userMustBeCreatedFirst=false
  • auth.disable-login - by default, disable-login for local is turned off (false). If you only want people to sign in via your IDP, turn this true

  • auth.userMustBeCreatedFirst - the user must exist in the database before they are allowed to login using an external auth provider. The default is false.

OAuth2

FeatureHub currently supports OAuth2 as a protocol, and currently three providers (Google, GitHub, Azure). It is built in such a way that you can easily support others.

Generalised OAuth Config

oauth2.providers=[comma seperated list of providers]
oauth2.redirectUrl=http://localhost:8085/oauth/auth
oauth2.adminUiUrlSuccess=http://localhost:8085/
oauth2.adminUiUrlFailure=http://localhost:8085/oauth2-failure
  • oauth2.redirectUrl - In this case, this needs to be registered with your OAuth provider as a web callback url. The actual url will depend on where you have installed it, and it only has to be visible to browsers in your organisation.

  • adminUiUrlSuccess and adminUiUrlFailure - are links back to your running FeatureHub system and indicate where to go. FeatureHub will set a cookie with the necessary information to authenticate the user on success.

Google Config

Basic details on setting up your credentials is located in Google’s help documentation. It needs to be allowed access to the profile (name) and email scopes.

For FeatureHub, your properties file needs to add a few configuration items:

oauth2.providers=oauth2-google
oauth2.providers.google.id=[CLIENT-ID]
oauth2.providers.google.secret=[CLIENT-SECRET]

FeatureHub knows all of the URLs necessary to ask Google for the negotiation phase.

GitHub Config

To authorise via GitHub, your properties file needs to add a few configuration items:

oauth2.providers=oauth2-github
oauth2.providers.github.id=[CLIENT-ID]
oauth2.providers.github.secret=[CLIENT-SECRET]

To obtain client id and secret follow these instructions to register OAuth app on Github under your organisation’s GitHub account.

Azure Config

Basic details of setting up Azure config are included here as they are a little difficult to find online. At the moment we are requesting openid, email, and profile scopes as only this combination provides us with the email address and name of the person. FeatureHub does not attempt to modify any data on any Azure account.

The fields we need for Azure are:

oauth2.providers=oauth2-azure
oauth2.providers.azure.tenant=[tenant-id]
# the azure ones expire after 24 months (from may 2021)
oauth2.providers.azure.id=[client-id]
oauth2.providers.azure.secret=[client-secret - what Azure calls a "value"]
  1. Open your Azure account, login and go here.

  2. Add a New Registration

  3. Choose the name - FeatureHub for instance and choose Single Tenant (the first option)

  4. Click Register and in the details you will find "Application (client) id" - this is your [client-id] for your configuration.

  5. Next in the details find "Display (tenant) ID" - this is your [tenant-id] from above.

  6. On the right side, find "Client credentials" and click the blue link that says "Add a certificate or secret".

  7. At the bottom of the page, choose "+ New client secret". Give it a name and choose a period of time to issue it for and Add it.

  8. At the bottom will now be listed your new secret, choose the Values column. Click the "copy" button to the right of it and paste that into the config under "[client-secret]". This is the last tiem you will see it as soon as you navigate away from that page, Azure will hide it from you.

You are now done.