Documentation Index

Fetch the complete documentation index at: https://help.nucleussec.com/llms.txt

Use this file to discover all available pages before exploring further.

Setting up Microsoft Entra ID SSO (Azure AD) For Nucleus VIP

  • 4 minute(s) read
Prev Next

This guide provides step-by-step instructions for setting up and testing Microsoft Entra ID SAML SSO integration with Nucleus VIP.

Please note: This is the set-up documentation for Nucleus VIP!

Nucleus VIP is a different product than Nucleus Security itself. Please ensure you are using the proper SSO set-up.

Microsoft Entra ID Configuration Requirements

Pre-requisites

  1. Microsoft Entra ID tenant with administrative access. (Note: You'll need an organizational account, e.g., [email protected], or an Azure account with an active subscription that allows you to create/manage a Microsoft Entra ID tenant.)

  2. Microsoft Entra ID application registration

  3. Valid domain for testing

Microsoft Entra ID App Registration Setup

Step 1: Create App Registration

  1.    Go to Microsoft Entra admin center (formerly Azure Portal for Azure AD functionalities)

  2.    Navigate to Microsoft Entra ID > Applications > App registrations

  3.    Click New registration

  4.    Configure: - Name: Nucleus VIP SAML or any other name you want to use for the app registration - Supported account types: Accounts in this organizational directory only - Redirect URI: Leave blank for now

  5.    Click Register

Step 2: Configure SAML

  1.    In your app registration, go to Authentication > Platform configurations > Add platform > Web

  2.    Add redirect URIs (Platform: Web): - https://vip.nucleussec.com/sso/acs/ (production)

  3.    Add logout URL: - https://vip.nucleussec.com/logout/ (production)

  4.    Save the configuration

Step 3: Configure Enterprise Application

  1. Go to Microsoft Entra ID > Enterprise applications (You might find this under Identity > Applications > Enterprise applications)

  2. Find your app (if it was automatically created from the app registration, it might have the same name. Note: If when you go to "Single sign-on" for this application, you don't see the option to select SAML, it might be configured for OIDC/OAuth by default. In this case, you may need to create a new Enterprise Application specifically for SAML. To do this, go back to the "Enterprise applications" list, click New application, select "Create your own application", give it a name, and choose "Integrate any other application you don't find in the gallery (Non-gallery)." Once the new application is created, proceed with the steps below using this new Enterprise Application instance.)

  3. Once you have your Enterprise Application for SAML connection, click on it.

  4. Go to Single sign-on (under Manage)

  5. Select SAML

  6. Configure basic SAML configuration: - Identifier (Entity ID): https://vip.nucleussec.com/sso/audience/ (for production) - Reply URL: https://vip.nucleussec.com/sso/acs/ (for production)

  7. Click Save

Step 4: Configure SAML Signing Options

  1. Ensure the correct signing options are selected for SAML communication.

  2.    Navigate to your SAML-configured Enterprise Application in Microsoft Entra ID.

  3.    Go to Single sign-on and in the SAML Certificates section, click Edit.

  4.    Verify or set the following:

  5.    Signing Option: Select Sign SAML response and assertion.

  6.    Signing Algorithm: Ensure this is set to SHA-256.

  7.    Click Save if you made any changes.

Step 5: Configure Attributes & Claims

Microsoft Entra ID provides some default claims when you set up SAML. Nucleus VIP application expects specific claims. You must ensure these are all present and correctly mapped in the 'Attributes & Claims' section of your SAML configuration in the Enterprise Application in Microsoft Entra ID.

Conceptually Required claims for Nucleus VIP:

Configuration Steps in Microsoft Entra ID:

  1.    Navigate to your SAML-configured Enterprise Application in Microsoft Entra ID.

  2.    Go to Single sign-on and in the Attributes & Claims section, click Edit.

  3.    Unique User Identifier (Name ID)

    1. The default value is often user.userprincipalname. This is generally suitable. Verify this setting.

  4.    Additional claims (email, givenname, name, surname):

    1. Review the existing claims. Claims like
      http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname are often present by default.

    2. Ensure their 'Source attribute' correctly maps to user.mail, user.givenname, user.userprincipalname, and user.surname respectively. Add them if they are missing, using their standard claim names.

  5.   Add a claim for external_id:

    1. Nucleus VIP expects the user's unique object identifier (from Entra ID's user.objectid) to be available under a specific claim name.

    2. You must configure Microsoft Entra ID to send a claim with this exact name (external_id) containing the user's object ID.

      1. Click + Add new claim.

      2. For Name, enter external_id.

      3. Leave Namespace blank.

      4. For Source attribute, select user.objectid.

      5. Click Save.

  6.    After making all changes, click Save at the top of the 'Attributes & Claims' page.

Step 6: Get Required Information

Collect the following information from Microsoft Entra ID:

  1. Tenant ID: Found in your Microsoft Entra ID Overview page

  2. Application (client) ID: Found in your app registration's Overview page

  3. Metadata URL: In the Single sign-on pane of your Enterprise Application locate the App Federation Metadata Url link and copy the full URL shown there. It will look similar to: https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<application-id>
    (The ?appid=... query string is required – keep it exactly as provided.)

  4. Domain: Your organization's email domain (e.g., nucleussec.com)

    1. This information will be used to configure the organization's SSO settings in Nucleus VIP (/organization/ > Settings > SSO Configuration).

Testing your setup

Create test users in your organization:

  1. In Microsoft Entra ID, ensure users exist in your tenant

  2. Users should have email addresses with your configured domain

  3. Assign users to your Nucleus VIP enterprise application in Microsoft Entra ID (under Users and groups in the Enterprise application)

Common Issues

1. Invalid Metadata URL

Error: Metadata URL is missing or Failed to validate SAML response

Solution: - Verify the metadata URL is the exact App Federation Metadata Url copied from the Single sign-on page (including the ?appid= query string). - Check that the URL is accessible from the server running Nucleus VIP.

2. Attribute Mapping Issues

Error: No email provided or missing user information

Solution: - Verify Microsoft Entra ID claims configuration (in the Enterprise Application's SAML settings) - Check that required attributes are being sent - Review the attribute mapping in apps/saml2_auth/saml.py

3. Certificate Validation Errors

Error: Certificate validation failed or Failed to verify signature

Solution: - Ensure Microsoft Entra ID SAML signing certificate is valid and correctly configured in your application (often done by consuming the metadata URL). - Check that the certificate chain is complete using SAML-tracer extension or similar tool, by comparing the certificate from the metadata URL with the certificate in authorization redirect response.

4. Organization Not Found

Error: Organization is not found

Solution: - Verify the organization's domain matches the user's email domain - Check that the organization has SSO enabled - Ensure the provider is set to 'AzureAD'