Skip to content
LogScale Self-Hosted
This is an archived version of the documentation downloaded from LogScale Documentation Archives. Up to date documentation, and documentation for later versions, is available on LogScale Documentation

# Authentication and identity providers

Authentication is the process of verifying the identity of a user, system, or entity attempting to access a resource. Authentication is distinct from authorization, which determines what an authenticated user is allowed to do within a system.

The following diagram shows an example of a standard OAuth/OIDC flow that LogScale supports. (Your actual flow may differ, depending on your identity provider and configuration.) A user initiates access to LogScale. LogScale redirects to the identity provider (IdP) and the user authenticates with the identity provider. The identity provider provides a token upon successful authentication and that token is forwarded to LogScale. LogScale validates the token and grants access.

sequenceDiagram participant User participant Browser participant LogScale participant IdP as Identity Provider (e.g., Okta, Azure AD) User->>Browser: Access LogScale Browser->>LogScale: Request access LogScale->>Browser: Redirect to IdP Browser->>IdP: Authentication request IdP->>Browser: Authentication prompt User->>Browser: Enter credentials Browser->>IdP: Submit credentials IdP->>IdP: Validate credentials IdP->>Browser: Authentication success + token Browser->>LogScale: Forward token LogScale->>LogScale: Validate token LogScale->>Browser: Grant access Browser->>User: Display LogScale dashboard

User authentication for an organization is only available for paid customers. To upgrade, contact the LogScale Sales Department. Assuming your organization is already a LogScale enterprise customer, you can use one of the identity providers or authentication methods described in these sections.

## Identity providers and other authentication methods

Although you can use LogScale for authenticating users, you can also use an identity provider, or you can use reverse proxy. LogScale supports a number of IdPs which you may already be using within your existing infrastructure, however, you can only have one identity provider configured in LogScale. The following links describe the various authentication methods and direct you to information about how to configure each authentication method to work with LogScale.

### Note

For self-hosted instances, it is only possible to have one authentication method.

- Security Assertion Markup Language (SAML) is an open standard for authentication and authorizing data between applications. LogScale supports Active Directory Federation Services, Azure AD/Entra ID, Duo Security, PingFederate, and Okta.

- OpenID (OIDC) is an open standard, decentralized authentication protocol.

- LogScale provides two ways to authenticate with LDAP: using LDAP and fetch group membership.

- OAuth is an open standard that can grant applications and others clients access to LogScale without giving them your password. LogScale supports Google, GitHub, and BitBucket Sign-In.

- Another way to accomplish single sign-on (SSO) in LogScale is by using a reverse proxy in front of LogScale.

- LogScale provides basic single user authentication to use for emergency access and basic testing. This should not be used in a production environment.

The following chart provides a high-level overview of the features available for each authentication method.

Feature | SAML | OIDC | LDAP | OAuth | Proxy
--- | --- | --- | --- | --- | ---
Single Sign-on | Yes | Yes | No | Yes | Yes
MFA Support | Yes | Yes | No | Yes | Depends
Group mapping | Yes | Yes | Yes | Limited | Yes
Implementation complexity | High | Medium | Medium | Low | High
Session management | IdP | IdP | LogScale | IdP | Proxy
Available for Self-hosted | Yes | Yes | Yes | Yes | Yes
Available for Cloud | Yes | Yes | No | No | No

## Authentication implementation planning

Before implementing authentication, ensure your environment meets these requirements:

- Network Requirements: Ensure bidirectional communication between LogScale and identity providers (ports 443/TCP).

- DNS Resolution: Verify that LogScale can resolve IdP hostnames and vice versa.

- Time Synchronization: NTP must be properly configured as time skew can break authentication.

- Certificate Preparation: Obtain and validate all required certificates in PEM format.

## Blocked IPs and IP ranges for authentication

The following networks are blocked for use with IdP for security:

ini

    # IPv4
    # See https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
    0.0.0.0/8          # RFC791 (https://www.iana.org/go/rfc791)
    0.0.0.0/32         # RFC1122 (https://www.iana.org/go/rfc1122)
    10.0.0.0/8         # RFC1918 (https://www.iana.org/go/rfc1918)
    100.64.0.0/10      # RFC6598 (https://www.iana.org/go/rfc6598)
    127.0.0.0/8        # RFC1122 (https://www.iana.org/go/rfc1122)
    169.254.0.0/16     # RFC3927 (https://www.iana.org/go/rfc3927)
    172.16.0.0/12      # RFC1918 (https://www.iana.org/go/rfc1918)
    192.0.0.0/24       # RFC6890 (https://www.iana.org/go/rfc6890)
    192.0.0.0/29       # RFC7335 (https://www.iana.org/go/rfc7335)
    192.0.0.8/32       # RFC7600 (https://www.iana.org/go/rfc7600)
    192.0.0.9/32       # RFC7723 (https://www.iana.org/go/rfc7723)
    192.0.0.10/32      # RFC8155 (https://www.iana.org/go/rfc8155)
    192.0.0.170/32     # RFC8880 (https://www.iana.org/go/rfc8880)
    192.0.0.171/32     # RFC7050 (https://www.iana.org/go/rfc7050)
    192.0.2.0/24       # RFC5737 (https://www.iana.org/go/rfc5737)
    192.31.196.0/24    # RFC7535 (https://www.iana.org/go/rfc7535)
    192.52.193.0/24    # RFC7450 (https://www.iana.org/go/rfc7450)
    192.88.99.0/24     # RFC7526 (https://www.iana.org/go/rfc7526)
    192.168.0.0/16     # RFC1918 (https://www.iana.org/go/rfc1918)
    192.175.48.0/24    # RFC7534 (https://www.iana.org/go/rfc7534)
    198.18.0.0/15      # RFC2544 (https://www.iana.org/go/rfc2544)
    198.51.100.0/24    # RFC5737 (https://www.iana.org/go/rfc5737)
    203.0.113.0/24     # RFC5737 (https://www.iana.org/go/rfc5737)
    240.0.0.0/4        # RFC1112 (https://www.iana.org/go/rfc1112)
    255.255.255.255/32 # RFC8190 (https://www.iana.org/go/rfc8190)

    # IPv6
    # See https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
    ::/128             # RFC4291 (https://www.iana.org/go/rfc4291)
    ::1/128            # RFC4291 (https://www.iana.org/go/rfc4291)
    ::ffff:0:0/96      # RFC4291 (https://www.iana.org/go/rfc4291)
    64:ff9b::/96       # RFC6052 (https://www.iana.org/go/rfc6052)
    64:ff9b:1::/48     # RFC8215 (https://www.iana.org/go/rfc8215)
    100::/64           # RFC6666 (https://www.iana.org/go/rfc6666)
    2001::/23          # RFC2928 (https://www.iana.org/go/rfc2928)
    2001::/32          # RFC8190 (https://www.iana.org/go/rfc8190)
    2001:1::1/128      # RFC7723 (https://www.iana.org/go/rfc7723)
    2001:1::2/128      # RFC8155 (https://www.iana.org/go/rfc8155)
    2001:2::/48        # RFC5180 (https://www.iana.org/go/rfc5180)
    2001:3::/32        # RFC7450 (https://www.iana.org/go/rfc7450)
    2001:4:112::/48    # RFC7535 (https://www.iana.org/go/rfc7535)
    2001:10::/28       # RFC4843 (https://www.iana.org/go/rfc4843)
    2001:20::/28       # RFC7343 (https://www.iana.org/go/rfc7543)
    2001:30::/28       # RFC9374 (https://www.iana.org/go/rfc9374)
    2001:db8::/32      # RFC3056 (https://www.iana.org/go/rfc3056)
    2002::/16          # RFC3056 (https://www.iana.org/go/rfc3056)
    2620:4f:8000::/48  # RFC7534 (https://www.iana.org/go/rfc7534)
    fc00::/7           # RFC8190 (https://www.iana.org/go/rfc8190)
    fe80::/10          # RFC4291 (https://www.iana.org/go/rfc4291)

In addition, multicast IPV4 addresses are also blocked for IdP:

ini

    # Multicast IPv4 addresses
    224.0.0.0/4

Last updated in v1.129.

## Group mapping between LogScale and identity providers

When using an identity provider that supports group mapping, it is important that the group names in LogScale match the group names provided in the identity provider.

For more information about group membership mapping and group synchronization, see Group Memberships and Group Synchronization.

## Change domain name

If an organization is changing their domain name, it is possible to modify the usernames of users in LogScale. The username is what is binding the user to the IdP and what ensures that the user ends up in the right organization. Since this can be maliciously used to gain access to content that you should not normally have access to, it requires a high-level system permission: `Change username`. The benefit of migrating users in this way is that they will keep the same underlying ID and access to everything within the product. A lot of internal logging is also logging the username of the user, so it should be noted that those logs would point to usernames that do not exist anymore. Usually the user ID is logged as well, so that can be used to correlate the logs.

To get a list of the users and user IDs, you can use the users() GraphQL query similar to the following:

gql

    query{  users(
        orderBy: {userField: USERNAME, order: ASC},
        )
        {username, id, email, displayName}
    }

LogScale recommends creating a system permission token for this purpose and deleting it once the operation is done. To create the token, run the following GraphQL mutation:

gql

    mutation{  createSystemPermissionsToken(
        input: {name: "UsernameMigrationToken", permissions: [ChangeUsername, ManageOrganizations]}
    )}

Add the token as a bearer token in the authorization header and execute the following mutation to alter the username:

gql

    mutation{updateUserById(input: {userId: "idOfUser", username: "newUsername@humio.com"}){clientMutationId}}

## Troubleshoot authentication

Generally speaking, you should tailor any troubleshooting to the specific method of authentication. However, all of the methods have some common troubleshooting actions.

If you get an error when trying to connect to your localhost, do the following to start debugging:

1. Open a terminal and go to the logs within the humio1 directory. An example of a command to do that is:

   ini

       cd /Users/<username>/Documents/Humio_Natively/mac_m1_humio/humio1/logs

2. Use `grep` to search all the logs to start debugging, such as:

   ini

       grep "<error_code>" *

#### Enter search term