OIDC

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 on-premise, ensuring that your Graylog login can be managed with a variety of OIDC-compliant identity providers.

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

Prerequisites

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.

Configure a New Identity Service

Navigate to System > Authentication to start the initial authentication process and configure your OIDC protocol.

  • To create a new authentication service, select Create service.

  • To edit an existing service, select the Edit button responding to the service you would like to update.

Authentication Credentials

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

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

AuthO Use Case

  1. Log into your existing Auth0 dashboard. You will need to create an application for Graylog.

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

  1. Once the Graylog application has been created, select this application in Auth0 to view your client credentials. These credentials will be required to configure your OIDC service in Graylog.

  1. Navigate to System >Authentication and select Create Service in the Graylog user interface.
  2. Select OIDC as the service in the drop down menu and click Get Started.
  3. Use the credentials from Auth0 to fill in the following fields and make your selections, including:
Field Description
Title
  • The title of the login screen when your users sign into Graylog via your single sign on (SSO) protocol.
    		•
    Description
  • Provides a general description of the identity provider selected (optional).
    		•
    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
  • Both of these values are provided in the Auth0 application.
    		•
    Token Verified Connect Timeout
  • We recommend the default value of 10 for this field.
    		•
    Default Role
  • The default role will populate as Reader; this is the basic level of access needed for most Graylog users and is therefore the recommended selection.
    		•

    6. Select Server Connection Check and Apply. The Server Connection Check allows Graylog to perform a basic consistency and connectivity check of the configuration. Any errors detected at this point will be noted in the UI and must be resolved in order to proceed.

    Group Synchronization

    Group synchronization is supported with OIDC-compliant identity providers. You can enable group synchronization in the configuration menu while you are setting up your authentication service or by selecting Edit in the Group Synchronization module for an existing authentication service.

    1. Select the Synchronize Groups check box to enable the service.

    2. Provide a list of group names to be synchronized with Graylog in the Group Claims box. The default value will be set as graylog_teams.

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

    Activation

    Once you have configured the service, activate your current service provider to enable the authentication protocol. 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

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

    Set the Google hd Claim Authentication Parameter

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

    1. To set this authentication parameter, navigate to the Authentication page and select Edit next to your Google authentication service.

    OIDC_Edit

    1. In the Claims menu, add the hd claim under Name and provide your organization's domain name in the Value field.
    2. Select Add.

    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 will 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 into 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. Navigate to System >Authentication in the Graylog interface.
    8. Click on Create Service.
    9. Select OIDC as the service in the drop down menu and 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.