Intro

I was recently working with a customer to configure Azure AD as the SAML provider for their ExtraHop appliances. Although the process is pretty well documented in the ExtraHop docs, it is spread out in a few locations and there are a couple of gotchas we ran into.

In this post, I will show you the process to configure your ExtraHop appliances for SAML authentication using Azure AD as the Identity Provider (IdP).

Software

The following software was used in this post.

  • ExtraHop Sensor (EDA) - 8.9.0

SAML Terminology

Some important terminology to be aware about SAML is as follows.

  • Identity Provider (IdP) - Authenticates users and provides user identity
  • Service Privider (SP) - Provides authorized access to resources based on identity from the IdP
  • Claim - Information about the user.
  • Token - Group of claims.

SAML Login Flow

The image below is directly from the Microsoft docs [1]

saml-login-flow.png

IdP SAML Requirements

In order for ExtraHop to use an IdP SAML authentication, the IdP must meet the following requirements.

SAML 2.0 Compliant

The IdP MUST support the SAML 2.0 standard

SP-initiated login flows

The IdP MUST support SP-initiated login flows. IdP initiated login flows are NOT supported.

Signed SAML Responses

The IdP MUST support signed SAML responses. Unsigned SAML responses are NOT supported.

Prerequisites

There are a couple of items to square away in both ExtraHop and Azure before we begin.

ExtraHop

Update the hostname to the FQDN and re-generate the SSL certificate. This ensures that we have the correct ACS URL in the SP Metadata configuration.

Hostname

On the Admin panel, browse to:

Update the hostname to the FQDN and hit Save.

SSL Certificate

Browse to: Admin panel.

Hit OK on the prompt that asks if you would like to regenerate the certificate.

Note

The web interface will restart at this step, but this does not effect the capture process so data will continue to be ingested and analyzed.

Azure

Add the Azure AD SAML ExtraHop application to enable SAML based authentication.

SAML Application

In the Azure Portal browse to

Search for Azure AD SAML Toolkit in the search bar. Select the application and rename it to Azure AD SAML ExtraHop then hit Create

Note

This post assumes that the Users/Groups are already created in Azure or synced to Azure from on-prem AD.

SAML Configuration

ExtraHop - SP Metadata

To complete the Azure side we need to SP metadata from the ExtraHop appliance. On the ExtraHop admin portal, browse to:

Select SAML from the dropdown and hit Continue.

On the next screen select View SP Metadata. You will need to note down the ACS URL and the Entity ID.

sp-metadata.png

Once you have that information browse to the SAML application in Azure AD to complete the configuration on the Azure side.

There are 3 steps to complete.

  1. Basic SAML Configuration
  2. Attributes & Claims
  3. SAML Certificates

Azure - Basic SAML Configuration

The table below lists the parameters and values that are required for the SAML configuration. The parameters are obtained from the ExtraHop SP metadata in the previous step.

Parameter Value
Identifier (Entity ID) urn:extrahop:saml:<entity-id-string>
Reply URL (Assertion Consumer Service URL) https://<extrahop-fqdn>/admin/sso/saml/acs/
Sign on URL https://<extrahop-fqdn>/

The image below shows an example configuration.

azure-saml-1.png

Azure - Attributes & Claims

The tables below list the parameters and values that are required for the SAML attributes and claims configuration.

Required Claims - UUID

The first claim is used as a unique identifier for users within the ExtraHop platform.

Claim Name Value
Unique User Identifier (Name ID) user.userprincipalname
Additional Claims - Identity

These next three claims are required by the ExtraHop platform. They MUST be sent in the SAML response or authorization will fail.

Claim Name Value
urn:oid:0.9.2342.19200300.100.1.3 user.userprincipalname
urn:oid:2.5.4.42 user.givenname
urn:oid:2.5.4.4 user.surname
Additional Claims - Authorization

These next set of claims define the authorization groups.

Note

For the authorization claims, both the claim name and value can be any user defined value. However, these names and values MUST exactly match what is configured in the ExtraHop SAML configuration.
Claim Name Value
user-level Multiple Conditions
packets-level Multiple Conditions
detections-level Multiple Conditions

The multiple conditions for the authorization claims are as follows.

Claim Name: user-level
User Type Scoped Groups Source Value
Any List of User Groups Attribute read-only
Any List of User Groups Attribute full-write
Any List of User Groups Attribute unlimited
Claim Name: packets-level
User Type Scoped Groups Source Value
Any List of User Groups Attribute full-write
Any List of User Groups Attribute unlimited
Claim Name: detections-level
User Type Scoped Groups Source Value
Any List of User Groups Attribute unlimited

Important

The ordering of the conditions within a claim is important. The LAST condition that is matched will be sent in the SAML response. For example, in the user-level claim, if a user is a member of a scoped group in both the full-write and unlimited claims, the user will be granted unlimited privileges.

The image below shows all the attributes and claims from the tables above.

claims-1.png

The image below shows the detailed view of the user-level claim. The other claims are configured in a similar manner.

claims-2.png

Azure - SAML Signing Certificate

By default, the SAML application in Azure AD does not sign SAML responses. Change the Signing Option dropdown to Sign SAML response and assertion.

saml-cert-config-1.png

Important

The IdP MUST support signed SAML responses to be compatible with the ExtraHop platform.

Download the SAML certificate: Certificate (Base64). This will be used in the ExtraHop SAML configuration in a future step.

saml-cert-config-2.png

Azure - Set up Azure AD SAML ExtraHop

The details in the image below are required for the ExtraHop configuration.

saml-sp-config-params-1.png

ExtraHop - IdP SAML Configuration

The table below shows how the parameters in the Azure configuration map to the parameters in the ExtraHop configuration.

Azure Value ExtraHop Value
Login URL SSO URL
Azure AD Identifier Entity ID

On the ExtraHop appliance, browse to the SAML configuration and add an identity provider.

Identity Provider

The table below list the configuration parameters for the identity provider section.

Parameter Value
Provider Name AzureAD
Entity ID <Azure AD Identifier>
SSO URL <Azure Login URL>
Public Certifiate <Azure BASE 64 certificate>
Auto-provision users tick
Enable this identity provider tick

eh-identity-provider-config-1.png

The certificate MUST be in the following format to be valid.

x509 certificate
-----BEGIN CERTIFICATE-----
<BASE64 ENCODING>
-----END CERTIFICATE-----
Privilege Levels

Details around the user privilege levels and what they allow access to in the ExtraHop platform can be found in the docs here . How these group mappings are decided is based on the organizations security policy.

The next 3 sections MUST exactly match what is configured in the SAML claims seciton in Azure.

User Privilege Attributes

The following table lists the permissions mappings for the user-level attribute.

ExtraHop Privilege Level SAML Claim
Unlimited privileges unlimited
Full write privileges full-write
Full read-only privileges read-only

eh-identity-provider-config-2.png

Packets and Session Keys

The following table lists the permissions mappings for the packets-level attribute.

ExtraHop Privilege Level SAML Claim
Packets and session keys unlimited

eh-identity-provider-config-3.png

Detections Access

The following table lists the permissions mappings for the detections-level attribute.

ExtraHop Privilege Level SAML Claim
All detections unlimited

eh-identity-provider-config-4.png

Finally, hit the Save button to complete the configuration.

With that done, the configuration is completed, and we can now test our ability to login and access the ExtraHop platform.

Testing Access

Hot Tip

You can use the SAML Tracer Firefox/Chrome plugin to monitor the flow of requests to and from the IdP. I recommend you install it and open its debug window prior to loggin in.

To test your access, open a private browser window to your ExtraHop appliance. You will see an option to login with AzureAD

eh-saml-login.png

When you press the Log in with AzureAD button, you will be redirected to the Microsoft login portal. Once authenticated, you will be signed in with SSO across all you other SSO enabled applications.

The image below from SAML tracer confirms that the details send back in the SAML response are the same details we have configured throughout this post.

saml-response-1.png

The privilege assignments can also be confirmed by looking in the audit log.

saml-login-log-1.png

Finally, confirm that the user is created in the local users configuration.

eh-saml-user.png

Troubleshooting

A couple of common issues I have run into and their resolution is below.

Required Claims Not Presented

This error occurs when ALL the required claims are not present in the SAML response.

saml-error-1.png

Resolution

Ensure ALL the required claims are configured in the IdP.

Unsigned SAML Response

ExtraHop requires the SAML reponses to be signed. If they are not, you will see the following error.

saml-error-2.png

Resolution

Ensure the IdP is configured to sign SAML responses.

Outro

In this post, I showed you how to configure your ExtraHop appliances to use SAML authentication with Azure AD as an IdP. Please enjoy your SSO experience now with 100% more ExtraHop.

References

1 https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/auth-saml

Tags