OIDC Authentication

The following article exclusively pertains to a Graylog Enterprise feature or functionality. To learn more about obtaining an Enterprise license, please contact the Graylog Sales team.

Graylog supports generic OpenID Connect (OIDC) authentication, ensuring that your on-premises Graylog login can be managed with a variety of OIDC-compliant identity providers.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

  • You must be a Graylog administrator to implement OIDC authentication.

  • Graylog extracts user information from either the ID token or the UserInfo endpoints and requires the following claims: preferred_username or email.

  • Required parameters for OIDC providers include:

    • openid

    • profile

    • email

Graylog Supported Identity Providers

These providers have been tested successfully with Graylog; however, you are encouraged to explore authentication with any OIDC-compliant provider that best fits your needs and environment.

Authentication Credentials

When creating or editing an authentication service, you are required to enter your authentication credentials on the Authentication Services page in the Graylog web interface. You must obtain these credentials from your identity provider. Navigation of each provider’s application is different, and you might need to consider certain specifications when configuring identity providers such as Google and Azure AD .

Configure OIDC Authentication

In the following use case, we guide you through the configuration of an OIDC service with Auth0.

  1. Log in to your Auth0 dashboard.

  2. Follow Auth0 documentation to create an application for Graylog.

    Hint: If you have multiple Graylog instances, you must create separate applications in Auth0 for each Graylog instance.

  3. Select this application in Auth0 to view your client credentials. You need these credentials to configure your OIDC service in Graylog.

  4. In Graylog, navigate to System > Authentication, then click Create service.
  5. Select OIDC from the drop-down menu, then click Get started.
  6. Fill out the following fields in the form:
    FieldDescription

    Title

    Enter a title for the login screen when your users sign in to Graylog via your single sign-on (SSO) protocol.

    Description

    (optional) Provide a general description of the identity provider selected.

    OIDC Base URL

    The base URL of your OIDC environment from the credentials provided by Auth0.

    Callback URL

    The OIDC callback URL is generated by Graylog beneath this field. In most cases, you can copy this suggested URL.

    Client ID and Client Secret

    Enter these values, which are provided in the Auth0 application.

    Token Verifier Connect Timeout

    Determine the time interval in seconds until connection resets. We recommend the default value of 10 for this field.

    Default Role

    Set the Graylog user roles you want to delegate through this synchronization. Any roles you include are assigned to all synchronized users.

    The default role populates as Reader, which is the basic level of access needed for most Graylog users and is therefore the recommended selection.

  7. Click Test Server Connection to validate the configuration. This test allows Graylog to perform a basic consistency and connectivity check of the configuration. Any errors detected are noted in the UI and must be resolved in order to proceed.

  8. Click Finish & Save Service to complete the configuration steps and return to the All Authentication Services page. Or, optionally, click Next: Group Synchronization if you intend to use the groups feature.

Group Synchronization

This is a Graylog Enterprise feature. A valid Graylog Enterprise license is required.

In addition to individual users, OIDC integration can be used to synchronize groups from OIDC-compliant identity providers to Graylog teams. You enable group synchronization in the configuration menu after the initial steps completed above.

You can complete the following steps directly after the section above. Or, to add group synchronization to an existing authentication service, click Edit in Actions column for the service on the All Authentication Services page.

  1. On the Group Synchronization tab, select the Synchronize Groups check box to enable group synchronization.

  2. Provide a list of group names that you want to synchronize with Graylog in the Group Claims field. The default value is set as graylog_teams.

  3. Select Finish & Save Service to being group sync.

Activation and Sign On

After you configure the service, activate your current service provider to enable the authentication protocol.

  1. Click the Authentication Services tab to return to the All Authentication Services page.

  2. Click Activate in the Actions column for the service you want to activate.

If you change service providers or need to update your settings, be sure to activate the new service from this menu.

Warning: Only one authentication service can be activated at a time for each Graylog instance.

OIDC_Image_2

After you set up your identity provider authentication with Graylog, a new log-in page appears when you log out to start a new Graylog session. To get to this screen:

  1. Log out of Graylog. A login page with the text "Login with default method" appears.
  2. Log in to Graylog with your identity provider credentials to authenticate as a new delegated group member.

Hint: If you experience any issues with your identity provider preventing login, remember that you can select Login with default method to log in to Graylog with your default administrator credentials.

Set the Google hd Claim Authentication Parameter

If you use OIDC with Google, you can restrict access to only members of your G Suite domain by adding an hd claim that matches your G Suite domain name.

Warning: You must set this parameter to restrict access; otherwise, anyone with an authenticated Google account can access your Graylog instance. We strongly recommend restricted access as a best practice for all, but it is especially necessary for self-managed, publicly available Graylog instances.

To set this authentication parameter:

  1. Navigate to the System > Authentication page in the Graylog web interface, then select Edit next to your Google authentication service.

    OIDC_Edit

  2. In the Claimssection, add the hd claim under Name and provide your organization's domain name in the Value field.
  3. Select Add.
  4. Click Finish & Save Service.

For more information regarding the hd claim in Google Identity, see the related Google documentation.

Configure the ID Token for Azure AD

If you choose to utilize Azure AD as an identity provider, you need to customize the information returned by Azure AD during authentication and authorization. Your user email must be included in the ID token to establish a successful connection with Graylog. Follow the steps below to set up the integration:

  1. Log in to your Azure AD account.

  2. Register an application for Graylog.

  3. Click Manage in the left sidebar and select Token Configuration.

  4. Click Add custom claim and select Token Type: ID.

  5. Scroll through the claims list and select email.

  6. Click Add.

  7. In the Graylog interface, navigate to System >Authentication.
  8. Click Create service.
  9. Select OIDC as the service in the drop-down menu, then click Get started.
  10. Use the credentials from your Azure account to fill in the fields and make your selections.

See the related Microsoft documentation for further information on Azure AD integration.

Further Reading

Explore the following additional resources and recommended readings to expand your knowledge on related topics: