FeatureHub Identity

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 setting up Azure.

Keycloak Config

Keycloak is new in 1.5.0. You need to select the realm the new client will be in, and then set up your new client. As part of that you will need to ensure:

  • it uses the openid-connect setup for your Client Protocol

  • the valid redirect URIs include the link to your Management Repository (e.g. http://localhost:8085/oauth/auth when using our example setups).

oauth2.providers=oauth2-keycloak
oauth2.providers.keycloak.secret=[insert-client-secret]
oauth2.providers.keycloak.url=[the main url for your keycloak server, e.g. http://localhost:8080]
oauth2.providers.keycloak.realm=[your realm name]
oauth2.providers.keycloak.id=[the name of the client you created]

This will enable Keycloak to be used as your authentication provider, so users can login using that method.

Generic OAuth2 Provider

If you have an IdP that isn’t listed above, you can still likely use it, its just a bit more configuration. This option requires you to provide your own icon, background colour and login text. Remember, any and all of these can be environment variables.

oauth2.providers=oauth2-generic
oauth2.providers.generic.auth-url=[full auth url, including https]
oauth2.providers.generic.token-url=[full token url, including https]
oauth2.providers.generic.id=[required, client-id]
oauth2.providers.generic.secret=[required, client-id]
oauth2.providers.generic.scope=[defaults to "profile email"]
oauth2.providers.generic.name-fields=[optional, field to find inside JWT for the user's name, defaults to "name"]
oauth2.providers.generic.email-field[optional, field to find inside JWT for user's email, defaults to "email"]
oauth2.providers.generic.icon.url=[required, full icon url, including https]
oauth2.providers.generic.icon.background-color=[required, background colour in 0x format, e.g. 0xFFF44336 is a redish colour]
oauth2.providers.generic.icon.text=[required,text to appear on button]

If your IdP needs the client secret to be Base64 encoded in the header, add this configuration:

oauth2.providers.generic.secret-in-header=true