SAML 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 SAML user authentication, ensuring that your on-premises Graylog login can be managed with a variety of standards-compliant identity providers. You can use a valid SAML identity provider to import user profiles and enable single sign-on (SSO) for your organization. You can also synchronize SAML group members to teams in Graylog.

This article explains the requirements for setting up SAML authentication and demonstrates the process in Graylog.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

You must be a Graylog administrator to implement SAML authentication.
You must have appropriate access credentials to your SAML identity provider.

Graylog Supported Identity Providers

These providers have been tested successfully for SAML configuration with Graylog. However, you are encouraged to explore authentication with any SAML-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, so be sure to check the documentation for your specific identity provider.

Configure SAML Authentication

In the following procedure, you need access to both the Graylog web interface and your identity provider administrative portal. These instructions assume you are already logged on to both.

In your identity provider portal, create the necessary SAML integration for single sign-on (SSO). For example, with Microsoft Entra ID, you create an enterprise application, then configure it for SSO. For Okta, you create an app integration, then configure it for SSO. You must check your provider's documentation for specific instructions!

To complete the configuration, you need to enter information from your Graylog instance. When you get to this point, proceed to the next step.
In the Graylog web interface, navigate to System > Authentication, then click Create service.
Select SAML from the dropdown, then click Get started.
On the IdP Configuration page, find the required values under the blue banner on the right side. Typically, the information you need to enter in your identity provider includes:
- Service Provider Entity ID: The Entity ID is generated by Graylog as a URL or other type of string. The generated value should work in most instances. However, you can customize the value or enter a value provided by your identity provider, if required. To change the value, update the Entity ID field in the Service Provider Config section of the form. It is essential that you have the same Entity ID value on both Graylog and your identity provider.
- Service Provider Assertion Consumer Service (ACS) URL: This value, also known as the reply URL, tells the identity provider where Graylog expects to receive the authentication token.
Copy the values provided by Graylog, then enter them where required in your identity provider configuration.
In the Graylog form, enter a title and description (optional) for this SAML authentication service.
In the Identity Provider Config section, enter the Metadata URL, then click Fetch. The metadata URL is a value provided by your identity provider and could have a different name. Check your provider's documentation.

With a metadata URL provided, the Fetch action fills in the remaining fields in the Identity Provider Config section. If the automatic configuration doesn't work with your provider, you need to provide the information in this section as follows:
- SSO Service Redirect URL and SSO Service POST URL: At least one of these fields is required.
- Entity ID and Certificate: Required fields.
- Other fields are optional.
Note that all of this information comes from your SAML identity provider configuration.
In the Service Provider Config section, create a certificate and private key to sign data that Graylog sends to the identity provider. Click Generate Credentials to allow Graylog to create the certificate/key pair. You can also upload an existing certificate/key pair in PEM format.
(Optional) Add your certificate to the identity provider. Although not required, this step is recommended for best security.
If you are planning to configure team synchronization, select Next: Team Sync, then proceed to the Group Synchronization section. Otherwise, select Finish & Save Service.
In your identity provider, complete any other required configuration.

The new SAML authentication service appears in Graylog in the table on the All Authentication Services page. See Activation and Sign On for next steps.

User Attribute Mapping and Roles

On the IdP Configuration page, the bottom of the form includes sections for User Attribute Mapping and Roles Configuration. In most cases, the default values provided work well and you can skip these sections.

For user attributes, the right side of the screen shows the default mappings that Graylog uses to extract information for each field. If your SAML provider uses any of these attributes to store the given information, then no action is required for that mapping. However, if your provider uses a different, custom attribute, you can provide it in the form.

In the Roles Configuration section, you can see that the Reader role is assigned by default to synchronized users. Typically, this is the role necessary for most users. If you want a different common permission set, adjust this setting. See Permission Management for more information.

SAML Group Synchronization

In addition to individual users, SAML integration you can synchronize groups from SAML-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 the Actions column for the service on the All Authentication Services page.

On the Team Sync tab, select the Enable Team Sync check box to enable group synchronization.
Add a SAML assertion attribute name that contains a list of group names in the Group Attribute Name field, if required. By default, Graylog uses the mapping shown on the right side of the page to extract group information. If your provider uses a custom value, then you must enter it here.
Select Finish & Save Service to begin group sync.

Activation and Sign On

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

Click the Authentication Services tab to return to the All Authentication Services page.
Click Activate in the Actions column for the service you want to activate.

If you change identity 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:

Log out of Graylog. A login page with the text "Login with SAML" appears.
Log in to Graylog with your identity provider credentials.

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.