Authenticating with SAML

Security Assertion Markup Language (SAML) is an open standard for authentication and authorizing data between applications. Humio implements the SAML 2.0 Web Browser SSO Profile. This means authentication is delegated to an existing identity provider (IDP) which is responsible for managing user credentials.

Leveraging an existing SSO solution in an organization provides Humio users with a seamless log-on experience: If they are already logged on through their SSO they will not be prompted for credentials. Instead, authentication will be handled transparently by Humio and the IDP. This means Humio will never see the credentials of the user since the authentication is delegated to the IDP. You should be able to use Humio with any SAML 2.0 provider.

These are the identity providers that Humio can be configured to use:

More information on these providers and how to integrate them with Humio is presented further down. Click on whichever you want in the list above, to jump to that part of this page.

Configure Humio

Humio needs to know the specifics about the IDP. This is configured through:

ini
AUTHENTICATION_METHOD=saml
PUBLIC_URL=$YOUR_SERVERS_BASE_URL
SAML_IDP_SIGN_ON_URL=$IDP_SIGNON_URL #  https://accounts.google.com/o/saml2/idp?idpid=C0453
SAML_IDP_ENTITY_ID=$IDP_ENTITY_ID    #  https://accounts.google.com/o/saml2?idpid=C0453
SAML_IDP_CERTIFICATE=$PATH_TO_PEM    #  /home/humio/GoogleIDPCertificate-humio.com.pem
AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN=true  # default is false

When a user tries to access Humio the authentication flow will start by redirecting the user to $IDP_SIGNON_URL. Upon a successful authentication the user will be redirected back to Humio where a Humio-specific access token will be issued. For the redirects to work properly a PUBLIC_URL must be configured. For details about the flow see the Wikipedia article about Web Browser SSO Profiles.

The $IDP_ENTITY_ID identifies your IDP and is used internally in the authentication flow.

The provided certificate must be in PEM format (see Privacy-Enhanced Mail). If you are running Humio in Docker make sure the file is accessible from the container by, for example, putting it in a read only directory as described in the Docker installation.

The redirect back to Humio is handled by the SAML Assertion Consumer Service endpoint located at http://$YOUR_HUMIO_URL:$PORT/api/v1/saml/acs. The SAML binding used in this interaction is the HTTP POST Binding. While the logon interaction from Humio to the IDP is done through a HTTP Redirect (GET) Binding.

Metadata about Humio as a SAML Service Provider is available at http://$YOUR_HUMIO_URL:$PORT/api/v1/saml/metadata.

If the AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN variable is set to the default value of false, users must be created in Humio before they can log in. If set to true, users are auto-created if they log in successfully.

Read more about Humio Configuration.

Synchronize Security Group Memberships

See Authorization for an overview on mapping groups.

First, configure Humio to automatically synchronize the groups upon successful login in Humio:

ini
SAML_GROUP_MEMBERSHIP_ATTRIBUTE=http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
AUTO_UPDATE_GROUP_MEMBERSHIPS_ON_SUCCESSFUL_LOGIN=true
Figure 1, Example Security Group

For each Security Group in your Single Sign On provider, you need a corresponding Humio group with the correct external provider mapping. That is, copy the GUID that identifies your Security Group.

Into the ‘External Provider’ tab of the corresponding Humio Group.

Figure 2, Corresponding Group in Humio

Last, add repositories or views to the mapped groups to give users access.

Access Token Lifecycle

When the SAML-specific authentication flow is finished and successful, a Humio access token is issued by Humio itself. Until the token expires, the IDP will not be involved in authentication of the user’s requests. The lifetime of the access token is 24 hours.

New User Accounts

If Humio encounters a new user that has been granted access through the IDP it will create the user in the context of Humio. For this purpose the NameId in the SAML authentication response will be used as the username property of the Humio user. The recommended username is the email.

humio
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">Username</saml:NameID>

By default, the user has no rights. So unless a user is otherwise granted access rights, he or she will not be able to do anything besides see an empty list of repos. You can use SAML roles to control access. Otherwise, the user needs to be added explicitly as a member or admin to a repo/view to be able to access it.

User Attribute Mapping

Instead of using NameId for mapping users from the IDP to Humio, a user attribute name can be configured:

ini
SAML_USER_ATTRIBUTE=email

In this case Humio will use the mail attribute from the IDPs SAML response after a successful authentication. Often whitelisting of Humio as an SP needs to be configured at the IDP level. Consult your vendor-specific IDP documentation.

Active Directory Federation Services

Active Directory

ADFS is a software component from Microsoft that runs on Windows. It can provide users with single sign-on access to Humio.

To configure the ADFS for integration with Humio, first add a new Relying Party Trust. Click Start and then select Enter data about the relying party manually and click Next.

In the Configure URL tab, enable support for the SAML 2.0 WebSSO protocol. Use http(s)://$YOUR_HUMIO_URL/api/v1/saml/acs

In the Configure Identifiers tab, add http(s)://$YOUR_HUMIO_URL/api/v1/saml/metadata. In the last tab, make sure to check Configure claims issuance policy for this application.

In the new pop-up, add a rule with the rule type, Send LDAP Attributes as Claims. In the table on the left side (LDAP attribute), select Email Addresses. Then, in the table on the right side (Outgoing claim type), select Name ID.

Now, add another rule, also with the rule type, Send LDAP Attributes as Claims. In the table on the left side (LDAP attribute), select Is-Member-of:DL. In the table on the right side (Outgoing claim type), select Group.

You will need to find the metadata XML at this URL, adjusting the domain address to your domain: https://<ADFSURL_PUBLIC_URL>/FederationMetadata/2007-06/FederationMetadata.xml>

You will also need the entityId as Idp Entity Id, as well as the <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" as Sign on URL, and X509Certificate as Certificate in Base 64

If you have a self-hosted installation of Humio, you need to save the certificate as a PEM file on the server.

To configure Humio on your own server, go to the top of this page on Configuring Humio.

See the Active Directory FS Documentation for more information.

Azure Active Directory

Azure Active Directory

Azure AD is Microsoft’s enterprise cloud-based identity and access management (IAM) solution. It can be used to access your Humio repositories.

Figure 3, Details for New App

To integrate Azure AD with Humio, you’ll need to create an app in Azure Active Directory. To do this, you’ll need first to sign in to the Azure portal. Then open Enterprise Applications and click New application. This will change the screen and you’ll see where you can then click Create your own application. The result will be an pop-up box link the one here:

Figure 4

Enter a name for the app, such as Humio. Choose Integrate any other application you don’t find in the gallery and click Create.

Now you’ll see a screen about creating the app. There will some large icon boxes, one of which reads, Set up single sign on. Click and then the choices of icon boxes will change. Click the one that’s labeled, SAML.

Click Edit in the Basic SAML Configuration tab and fill in theses fields:

  • Set Identifier (Entity ID) to $YOUR_HUMIO_URL/api/v1/saml/metadata

  • Set Reply URL to $YOUR_HUMIO_URL/api/v1/saml/acs

  • Leave Sign on URL and Relay State blank.

When you’re done, click Save.

Click Edit under User Attributes & Claims. Then click on the first Required claim. Ensure that name identifier format is set to Email address.

To set up group synchronization, create a group claim by clicking Edit under User Attributes & Claims tab. Optionally, assign ysers by selecting Users and Groups. There you’ll assign users or groups to your application.

Figure 5

You finished configuring Azure AD to work with Humio. Now, you need to configure Humio to work with Azure AD. To do this, you will need some information from the Azure AD configuration, which you can find by clicking on the View step-by-step instructions under Set up Humio.

You may also want to set the relay state. To do this, go to Single Sign On tab in Azure AD, and click Edit under Basic SAML Configuration (see screenshot here). Paste the URL into the field under Relay State. Click Save when you’re done.

To configure Humio on your own server, go to the top of this page on Configuring Humio.

See the Azure Active Directory Documentation for more information on Azure AD.

Duo Security

Duo Security

Duo security provides a great way of authenticating your users for your self-hosted Humio installation.

Before configuring SAML authentication, a few things needs to be in place:

  • Duo Access Gateway (DAG) installed and configured with at least one Authentication Source.

  • Familiarize yourself with Humio’s configuration.

  • Make sure you have one root account added, typically by adding your email address in the administration section of Humio’s Web UI.

First, open your DAG and go to the Applications page. Take note of the SSO URL and Entity ID parameters. Save the certificate to a known location on your Humio host. Next, change the following configuration variables in Humio to look like this:

ini
AUTHENTICATION_METHOD=saml
PUBLIC_URL=$YOUR_SERVERS_BASE_URL
SAML_IDP_SIGN_ON_URL=$IDP_SIGNON_URL
SAML_IDP_ENTITY_ID=$IDP_ENTITY_ID
SAML_IDP_CERTIFICATE=$PATH_TO_PEM

The SAML_IDP_SIGN_ON_URL should be set to the value of “SSO URL” from the DAG. The SAML_IDP_ENTITY_ID should be set to the value of “Entity ID” from the DAG. And the SAML_IDP_CERTIFICATE should contain the location of your DAG certificate. If you’re running the Docker image of Humio, please make sure you’ve mounted a certs volume by adding, -v /certs:/certs:ro.

See the Configuration Variables reference page for more information on each of these environment variables.

When you’re finished editing the configuration of Humio, restart it. Then read the output of http://$YOUR_HUMIO_URL:$PORT/api/v1/saml/metadata and take note of a couple of the values: The md:EntityDescriptor#entityID should be a url starting with your PUBLIC_URL, followed by /api/v1/saml/metadata. The md:AssertionConsumerService#Location should be a url starting with your PUBLIC_URL, followed by /api/v1/saml/acs.

Now, log into your Duo account and add a new Generic SAML Service Provider. Set the Entity ID to md:EntityDescriptor#entityID, Assertion Consumer Service to md:AssertionConsumerService#Location, and NameID Attribute to email.

When you’re done, save the configuration file and upload it to your DAG.

Okta

Okta

Humio allows for the integration of many applications. If you want to integrate Okta into Humio, you can do so by creating an application (i.e., an app) in Okta. To do this, you’ll have to use Okta’s system, in particular the SAML (Security Assertion Markup Language) section. This is used to authenticate and authorize the app.

Creating an App in Okta

Figure 6, New App in Okta

From the main page of the Okta user interface, click on Admin. This will bring you to the Admin Dashboard. From there, go to applications by clicking the button labeled, Applications in the header.

Next, click on the button labeled, Add Application. Then click on the button labeled, Create New App. You’ll see a box similar to the one in Figure 6. Incidentally, you can click on any image on this page to enlarge it. Now, choose Web as the platform to use and select SAML 2.0 for the sign-on method. Then click, Create.

Figure 7, General Settings in Okta

You’ll now be asked to give your application a name. Name it Humio. While you’re at it, upload an image for the login button. You can use our logo for this purpose, if you’d like. When you’re finished, click Next to continue.

You should be on the SAML Settings configuration section. In the General area, you will need to set a few values to tell Okta how to connect to Humio. The table below lists all of the fields you’ll need to set, and the values to give them:

Field

Value

Single Sign on URL

http(s)://$YOUR_HUMIO_URL/api/v1/saml/acs

Audience URI (SP Entity ID)

http(s)://$YOUR_HUMIO_URL/api/v1/saml/metadata

Name ID Format

EmailAddress

Application Username

Email

To understand better where these values are entered, you can see an example in the screenshot shown in Figure 7 above.

Figure 8

Next, you’ll have to add a single attribute in the Group Attribute Statements area of the SAML settings configuration. Set its Name to a value of group, with the Name format set to Basic. Set the Filter to Matches regex with the value as .*. When you’re finished doing all of that, click Next.

For the Feedback step, choose “I’m an Okta customer adding an internal app”—assuming you are one. Check the box where it says, “This is an internal app that we have created”. When you’ve done this, click the button labeled, Finish.

On the next page, you should see a detailed view of the application you just created. On that page, click View Setup Instructions. This will provide you with three key pieces of information you’ll need to configure Humio to work with Okta: the Identity Provider Single Sign-On URL; the Identity Provider Issuer; and the X.509 Certificate. You can see all of this in Figure 8. Leave that page open for reference for when you’re configuring Humio in a moment.

At this point, Okta is configured to work with Humio. However, there is a little more to do, but mostly on your Humio system.

Configuring Humio

Figure 9

After you’ve done what needs to be done to prepare Okta for integrating with Humio, you’ll need to configure Humio. What you’ll do will depend on whether you’re using Humio Cloud or are self-hosting Humio on your own server.

For a self-hosted installation of Humio, see Configuring Humio.

When you’ve finish preparing Humio, go to the Sign On tab in Okta (see Figure 9). In the Settings section, click on Edit. This will provide you an input box labeled, Default Relay State. Paste the URL for Humio into that field and save when done.

You’ll need to give users in Okta permissions to use the app. Assign the application to any users or groups you want to have access to Humio. See Okta’s instructions on how to do this. Otherwise, if everything went according to the instructions on this page, you’re now ready to use Okta with Humio.

PingFederate

PingFederate

PingFederate serves as a global authentication authority that allows any user to access securely Humio. It integrates with identity standards like SAML, OAuth, and OpenID Connect. It can be deployed on-premise or in the cloud.

To configure the PingFederate for integration with Humio, first complete the instructions in Creating an SP Connection with your IdP PingFederate. From SP Connections, select the SP Connection.

Then navigate to Browser SSO ‣ Configure Browser SSO ‣ SAML Profiles tab. From the list of profiles shown there, select SP-INITIATED.

Click Next twice, and go to Configure Assertion Creation ‣ Attribute Contract. At that point you’ll add email as the Attribute Contract.

From SP Connections, select SP Connection, then go to Browser SSO ‣ Protocol Settings ‣ Configure Protocol Settings ‣ Allowable SAML Bindings.

You’ll then see a list of options. Select REDIRECT and click Save.

Now, click Server Configuration ‣ Administrative Functions ‣ Metadata Export. Then click Next.

Select SP Connection again and click Next. Then select the Signing Certificate, and click Next.

At this point, a metadata file has been generated. This file holds information you will need to set up Humio to communicate with PingFederate. Export that file and then click Done.

You’re now ready to configure Humio, using the metafile you just exported.

To configure Humio on your own server, see Configuring Humio.

See the Ping Identity Documentation for more information on PingFederate.