Authenticating with OAuth Protocol

OAuth Protocol

OAuth is an open standard that may be used to grant access to Humio to applications and others without giving them your password.

Humio supports the OAuth 2.0 login flow for the following providers:

  • Google Sign-In

  • GitHub Sign-In

  • BitBucket Sign-In

Providers must be configured on the Humio server, as seen in the section for each provider.

You can enable several providers at the same time by setting multiple provider configurations.

Before you get started you must create OAuth Apps with the provider and get client_id and client_secret, and configure your redirect_uri.

In order for OAuth authentication to work properly you must provide a URL where Humio can be reached from the browser, see the configuration option PUBLIC_URL.

BitBucket Sign-In

BitBucket

To use BitBucket as a single sign-in method with Humio, you’ll first have to set up BitBucket. Once you do, go to your Account Settings and create an OAuth Consumer.

Set the Callback URL to %PUBLIC_URL%/auth/bitbucket. Then grant the account:email permission and Save.

Once that’s done, find the Key (Client Id), and Secret (Client Secret) in the list of consumers. You’ll need that for Humio’s configuration file. You can read more about integrating an application on BitBucket on their Setup Instructions.

Now that your consumer is created, you can configure Humio to use authenticate with BitBucket. Edit the Humio configuration file to include the following lines:

ini
AUTHENTICATION_METHOD=oauth
PUBLIC_URL=$YOUR_SERVERS_BASE_URL
BITBUCKET_OAUTH_CLIENT_ID=$CLIENT_ID # The Key from your BitBucket OAuth Consumer
BITBUCKET_OAUTH_CLIENT_SECRET=$CLIENT_SECRET # The Secret your BitBucket OAuth Consumer
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true  # default is false

For more about Humio configuration, check the Environment Variables documentation page.

Google Sign-In

Google Cloud

Detailed Setup Instructions: https://developers.google.com/identity/sign-in/web/sign-in

  • Create a Project from the Google Developer Console,

  • Create a OAuth Client ID on the Credentials Page,

  • Add an Authorized redirect URI: %PUBLIC_URL%/auth/google

where %PUBLIC_URL% is the same value as Humio is configured with. This can be http://localhost:8080/auth/google during development. Login will fail if the redirect_uri is not set correctly.

Once your app is created you can configure Humio to authenticate with Google.

Configuration Properties

ini
AUTHENTICATION_METHOD=oauth
PUBLIC_URL=$YOUR_SERVERS_BASE_URL
GOOGLE_OAUTH_CLIENT_ID=$CLIENT_ID #The client_id from your Google OAuth App
GOOGLE_OAUTH_CLIENT_SECRET=$CLIENT_SECRET The #client_secret your Google OAuth App
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true  # default is false

Read more about Environment Variables.

GitHub Sign-In

GitHub

Setup Instructions: https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/

Quick Summary

  • Create an OAuth App from your organization/user settings page,

  • Set the Authorization callback URL: %PUBLIC_URL%/auth/github

Read more about Environment Variables.

Once your app is created you can configure Humio to authenticate with GitHub.

ini
AUTHENTICATION_METHOD=oauth
PUBLIC_URL=$YOUR_SERVERS_BASE_URL
GITHUB_OAUTH_CLIENT_ID=$CLIENT_ID # The client_id from your GitHub OAuth App
GITHUB_OAUTH_CLIENT_SECRET=$CLIENT_SECRET # The client_secret your GitHub OAuth App
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true  # default is false

Read more about Environment Variables.

OAuth with Auth0

Auth0

Humio can be configured to authenticate users through Auth0. Unless you have specific requirements, Auth0’s free tier is sufficient.

You can choose which Identity Providers (such as Google, GitHub and Facebook) you wish to allow for authentication.

Auth0 keeps information about your users. This may require you to have a Data Processing Agreement with Auth0. If all you need is Google and GitHub, you can use Humio’s built-in support for several providers and avoid storing your users’ personal data with a third party provider.

Create a Humio App

You should create an Auth0 Regular Web Application specifically for Humio. Once the application is created you will need to set up properties.

Find your application’s configuration. Under the application’s Settings page find Client ID, the Client Secret, and the Domain. We’ll need these for Humio’s settings. You will also have to change some variables in Humio’s configuration file:

ini
AUTHENTICATION_METHOD=auth0
AUTH0_CLIENT_ID=$YOUR_CLIENT_ID
AUTH0_CLIENT_SECRET=$YOUR_CLIENT_SECRET
AUTH0_DOMAIN=$YOUR_AUTH0_DOMAIN
PUBLIC_URL=$YOUR_SERVERS_BASE_URL

See the Environment Variables reference page to learn how to set these and other variables for your Humio cluster.

Set the Callback URL

In order to avoid CSRF attacks you must set the Allowed Callback URLs field to %PUBLIC_URL%/auth/auth0, such as https://www.example.com/auth/auth0, where %PUBLIC_URL% is the value of the Humio configuration option PUBLIC_URL.

Using Auth0 authentication for Humio requires that you set the PUBLIC_URL configuration option.

Map Auth0 Roles

Using the Auth0 Authorization Extension you can define Auth0 roles and map them to Humio groups. For details on how groups work in Humio see Authorization.

The users/roles defined at top-level in the Auth0 dashboard do not work with this. This only works for users/roles defined inside the Auth0 authorization Extension, which is found in the left side Extensions menu item.

The Auth0 Authorization Extension requires an Auth0 Rule of its own installed to work, and additionally you need to create a rule to copy the roles into the token returned by Auth0 to Humio. This additional rule could look like this

humio
// rule to copy user's roles into the returned token
function (user, context, callback) {
  const assignedRoles = (context.authorization || {}).roles;
  context.idToken["https://auth0-example.humio.com/roles"] = assignedRoles;
  callback(null, user, context);
}

The attribute https://auth0-example.humio.com/roles in this example is the user-configurable attribute that will hold the Auth0 roles. If you configure AUTH0_ROLES_KEY=https://auth0-example.humio.com/roles (in Humio) and add the above Auth0 Rule in the Auth0 dashboard, the assigned roles are transferred to humio in the AWT token and are made available to Humio. If AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN is not set, then users must already have been created inside Humio’s UI.

ini
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true
AUTO_UPDATE_GROUP_MEMBERSHIPS_ON_SUCCESSFUL_LOGIN=true

The property AUTO_UPDATE_GROUP_MEMBERSHIPS_ON_SUCCESSFUL_LOGIN controls that group membership rules in Humio are transferred upon login. When deleting a user or changing access rights in Auth0, changes are not reflected until you log into Humio again.