SAML Authentication

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.

Logging in with SAML Authentication

When SAML-based authentication has been enabled, users must use the Enterprise Login feature of the login screen, entering their email address into the Enterprise Login box.

Login Window

Figure 203. Login Window


Users must use the enterprise login route, even if you've configured login through a service supported natively by Humio (i.e. Google, Github or Bitbucket).

Configure Humio for Cloud

Humio needs to know the specifics about the IDP.

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 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.

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 auto create user on successful login is enabled, users must be created in Humio before they can log in. If set to true, users are auto-created if they log in successfully.

Configure Humio for Self-Install

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

ini files
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.

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 Configuration Settings.

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.