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

## Authenticate with OpenID Connect

LogScale supports authenticating with any provider following the OpenID Connect standard. When OpenID Connect is configured, LogScale accepts OpenID tokens issued by the OpenID Connect provider (LogScale acts as a resource in OpenID Connect terms). This is useful if you are running LogScale behind a proxy that handles authentication.

In addition to acting as a resource, LogScale can also act as a client responsible for authenticating users (a relying party in OpenID Connect terms). This is similar to other OAuth authentication flows LogScale supports.

The diagram illustrates how OpenID Connect (OIDC) authentication works with LogScale. LogScale can function in two roles within the OIDC framework:

1. As a Resource where LogScale accepts tokens issued by an OIDC provider

2. As a Relying Party (Client) where LogScale handles authentication through an OIDC provider

sequenceDiagram participant User participant Browser participant LogScale as LogScale participant IDP as OIDC Provider Note over User, IDP: LogScale as OIDC Relying Party (Client) Flow User->>Browser: Attempts to access LogScale Browser->>LogScale: Requests access to protected resource LogScale->>Browser: Redirects to OIDC provider Browser->>IDP: Redirects with client_id, redirect_uri, scope, etc. IDP->>Browser: Presents login page User->>Browser: Enters credentials Browser->>IDP: Submits login credentials IDP->>IDP: Authenticates user IDP->>Browser: Redirects with authorization code to redirect_uri Browser->>LogScale: Sends authorization code LogScale->>IDP: Requests tokens with authorization code + client_secret IDP->>LogScale: Returns ID token, access token, refresh token LogScale->>IDP: Validates tokens & requests user info (if needed) IDP->>LogScale: Returns user information LogScale->>LogScale: Creates session & maps OIDC claims to user profile Note right of LogScale: Maps username from claim<br>(configurable via OIDC_USERNAME_CLAIM)<br>Maps groups from claim<br>(configurable via OIDC_GROUPS_CLAIM) LogScale->>Browser: Returns authenticated session Browser->>User: Shows LogScale interface Note over User, IDP: Alternative: LogScale as Resource (Token Validation Only) User->>Browser: Attempts to access LogScale with token Browser->>LogScale: Sends request with OIDC token LogScale->>LogScale: Validates token signature using JWKS LogScale->>LogScale: Verifies audience, issuer, expiration LogScale->>LogScale: Extracts username & group info from claims LogScale->>Browser: Returns authenticated session if token valid

### Create an OpenID Connect app

### Important

Prior to performing the steps below, make sure that you have a fully activated Okta account.

Log in and navigate to the main page of the Okta interface:

1. Click Adminto navigate to the Admin Dashboard. From there, click Applications and select Applications.

   Figure 93. Navigating to the Applications Section in Okta

2. Next, click Create App Integration.

   Figure 94. Starting the App Integration Process

3. Select OIDC - OpenID Connect and Web Application. Click Next.

   Figure 95. Selecting OpenID Connect App Type in Okta

4. Name the app, for example LogScale OIDC, and upload an image (optional). Enter the following:

   - Grant Type: Client Credentials

   - Sign-in redirect URLs: $LOGSCALE_URL/auth/oidc

   - Sign-out redirect URLs: remove, if existing. Optional.

   - Assignments: Select Skip Group Assignment for now

   Click Save.

   Figure 96. Configuring OIDC Application Settings in Okta

   Figure 97. Configuring Redirect URLs and Assignments in Okta

5. Click the Sign On tab of the app, and under OpenID Connect ID Token Set Issuer to Okta URL (https://dev-84903084.okta.com). Set Group claims filter to `groups` and select `Matches regex` with the regex pattern `.*`. Click Save.

   Figure 98. Configuring Group Claims in OpenID Connect ID Token

### Configure LogScale to use OpenID Connect

To configure OIDC to work with LogScale you must add the necessary environment variables to your configuration and set the values. To read more about configuration, see Configuration Settings. It is necessary to setthe following parameters in `humio-config.env` for running LogScale as either a relying party or resource:

Environment variable | Description | Example
--- | --- | ---
`OIDC_PROVIDER` | Required. URL to the OpenID Connect provider. The provider URL must match the issuer reported by the OpenID provider exactly. | https://auth.example.com
`OIDC_AUDIENCE` | The audience to expect in a JWT. Defaults to the client ID, if set, and to "humio" otherwise. | logscale-app
`OIDC_USERNAME_CLAIM` | The name of the claim to interpret as username in LogScale. The value in the claim must be a string. Defaults to "humio-user". Can be set to "email" if using emails as usernames. | email
`OIDC_GROUPS_CLAIM` | Optional. The name of the claim to interpret as the groups in LogScale. The value in the claim must be an array of strings. Defaults to "humio-groups". | groups
`OIDC_CACHE_USERINFO_MS` | Optional. How long user info is cached on a LogScale node in milliseconds. Defaults to 600000 (10 minutes). | 600000
`PUBLIC_URL` | Base URL of the LogScale server. Required for OIDC client setup. | https://logscale.company.com
`OIDC_USE_HTTP_PROXY` | Optional. If running LogScale with an HTTP Proxy and you want to use it for OpenID Connect, sets whether to use the HTTP Proxy for calling OIDC. Defaults to "true". | true
`AUTHENTICATION_METHOD` | Specifies the authentication method. Set to `oauth` to enable OIDC authentication flow. | oauth
`AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN` | Whether to automatically create a user in LogScale after successful authentication. Defaults to "false". | true

LogScale will use the OpenID Connect Discovery endpoint (`%OIDC_PROVIDER%/.well-known/openid-configuration`) to configure the remaining parameters automatically. If your provider does not have such an endpoint, specify the following parameters:

Environment variable | Description | Example
--- | --- | ---
`OIDC_AUTHORIZATION_ENDPOINT` | A URL to the endpoint a user should be redirected to when authorizing. Required for clients. | https://auth.example.com/authorize
`OIDC_TOKEN_ENDPOINT` | A URL to the token endpoint used to exchange an authentication code to an access token. Required for clients. | https://auth.example.com/token
`OIDC_TOKEN_ENDPOINT_AUTH_METHOD` | The authentication method used to authenticate LogScale against the token endpoint. Can either be `client_secret_basic` to place the client ID and secret in basic auth, or `client_secret_post` to place the client ID and secret in post data. | client_secret_basic, or `client_secret_post` if `client_secret_basic` is not supported as per the discovery endpoint.
`OIDC_USERINFO_ENDPOINT` | Required. A URL to the user info endpoint used to retrieve user information from an access token. | https://auth.example.com/userinfo
`OIDC_JWKS_URI` | Required. A URL to the JWKS endpoint for retrieving keys for validating tokens. | https://auth.example.com/jwks

To use OIDC as a client, `PUBLIC_URL` must be set, LogScale must be registered as a client with your OpenID provider, and the provider must allow `%PUBLIC_URL%/auth/oidc` as a valid redirect endpoint for the client. The following parameters can be used to configure client setup:

Environment variable | Description | Example
--- | --- | ---
`OIDC_OAUTH_CLIENT_ID` | Client ID of your OpenID application. Required for client setup. | logscale-client
`OIDC_OAUTH_CLIENT_SECRET` | Client secret of your OpenID application. Required for client setup. | s3cr3t-k3y-v4lu3
`OIDC_SERVICE_NAME` | Optional. The display name of the OIDC provider on the sign-in page of LogScale. Defaults to "OpenID Connect". | Company SSO
`OIDC_SCOPES` | Optional. Comma-separated list of scopes to add in addition to the default requested scopes (`openid`, `email`, and `profile`). | groups,offline_access

Below is an example of a configuration file:

ini

    AUTHENTICATION_METHOD=oauth
    AUTO_CREATE_USER_ON_SUCCESSFUL_LOGIN= True
    AUTO_UPDATE_GROUP_MEMBERSHIPS_ON_SUCCESSFUL_LOGIN= True # default is false
    PUBLIC_URL=$YOUR_SERVERS_BASE_URL
    OIDC_PROVIDER=https://dev-xxxxx.okta.com #the provider URL
    OIDC_USERNAME_CLAIM=email
    OIDC_SCOPES=email
    OIDC_OAUTH_CLIENT_ID=xxxxxxxx #The client_id from your OpenID Connect Application
    OIDC_OAUTH_CLIENT_SECRET=xxxxxxxx #The client_secret your OpenID Connect Application
    OIDC_AUTHORIZATION_ENDPOINT=https://dev-xxxxx.okta.com/oauth2/v1/authorize
    OIDC_TOKEN_ENDPOINT=https://dev-xxxxx.okta.com/oauth2/v1/token
    OIDC_USERINFO_ENDPOINT=https://dev-xxxxx.okta.com/oauth2/v1/userinfo
    OIDC_JWKS_URI=https://dev-xxxxx.okta.com/oauth2/v1/keys
    OIDC_TOKEN_ENDPOINT_AUTH_METHOD=client_secret_post

#### Enter search term