Skip to main content

Azure Active Directory

AuthTeams

Microsoft Entra ID, formerly known as Azure Active Directory, is an identity service that provides SSO and authentication.

Integrating Cortex with Entra ID allows you to:

  • Automatically discover and track Entra ID teams and team memberships
  • Track ownership of entities
  • Create Scorecards that track progress and drive alignment on projects involving your Entra ID teams
caution

For information on configuring Entra ID SSO for logging in to Cortex, see the Microsoft Entra ID SSO documentation.

How to configure Entra ID with Cortex​

caution

If you do not see the settings page you're looking for, you may not have permission to access that page. Please contact your admin for assistance.

Step 1: Register and configure a new Active Directory application​

  1. Follow Microsoft's documentation to register a new single tenant Entra ID application.
  2. In your Entra ID admin center, navigate to your new application, and then to API Permissions. Add the following permissions:
    • Microsoft APIs > Microsoft Graph > Application permissions > User > User.Read.All
    • Microsoft APIs > Microsoft Graph > Application permissions > Group > Group.Read.All
  3. Click Grant Admin Consent to grant permissions for all accounts in the directory.
  4. Navigate to Certificates & secrets and click New client secret.
    • Note that you will need to rotate the secret before the expiration date you set for it.
  5. Navigate to the application's Overview page and copy the client ID. You will need the client ID and secret in the next steps.

Step 2: Configure the integration in Cortex​

  1. In Cortex, navigate to the Azure Active Directory settings page:
    1. In Cortex, click your avatar in the lower left corner, then click Settings.
    2. Under "Integrations", click Azure Active Directory.
  2. Configure the integration form:
    • Tenant ID: Enter your Entra ID tenant ID.
    • Client ID and Client secret: Enter the client ID and secret you generated in the previous steps.
  3. Click Save.
    • You will be redirected to the Azure Active Directory settings page in Cortex, where you can optionally set a group filter to limit which groups are pulled in from Entra ID.

How to connect Cortex entities to Entra ID​

Import entities from Entra ID​

You can manually import entities from Azure Active Directory:

  1. In the main nav of Cortex, click Catalogs > All entities.
  2. On the right side of the Entities page, click Import entities.
  3. Select the entity type.
  4. On the "Import entities" page, select Azure Active Directory.
  5. A list of discovered entities will appear. Click an entity to add it.
    • If your expected entities do not appear, click Sync entities in the upper left corner of the "Import entities" page.
  6. When you are finished adding entities, click Add.

Editing the entity descriptor​

You can define the following block in your Cortex entity descriptor to add your Entra ID group as an owner. 
x-cortex-owners:
  - type: group
    name: Engineering # group name in Entra ID
    provider: ACTIVE_DIRECTORY

The group name is case-sensitive and should be exactly the same as in Entra ID.

Expected results​

Teams page​

Under Catalogs > Teams, you will see teams and team members pulled in from Entra ID.

Entity pages​

If you have ownership of entities set up, then Azure AD teams and users will be listed in the Owners page for an entity.

Scorecards and CQL​

With the Entra ID integration, you can create Scorecard rules and write CQL queries based on Entra ID teams.

See more examples in the CQL Explorer in Cortex.

All ownership details

A special built-in type that supports a null check or a count check, used to enforce ownership of entities.

Definition: ownership: Ownership | Null

Example

An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:

ownership.teams().length > 0
All owner details

List of owners, including team members and individual users, for each entity

Definition: ownership.allOwners()

Example

The Scorecard might include a rule to ensure that entity owners all have an email set:

ownership.allOwners().all((member) => member.email != null)
Team details

List of teams for each entity

Definition: ownership.teams(): List<Team>

Example

The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:

ownership.teams().all(team => team.description != null and team.isArchived == false)

Background sync​

Cortex conducts an ownership sync every day at 6 a.m. UTC.

FAQ and Troubleshooting​

Why were all my Entra ID users unexpectedly deleted after rotating my client secret?​

Updating your configuration can cause a temporary deletion of users. When you delete the old secret from your Azure AD configuration in Cortex, a sync is triggered to delete the users. The addition of the new secret to your configuration will trigger a sync to add the users. There may be a delay before seeing the users re-added.

Still need help?​

The following are all the ways to get assistance from our customer engineering team. Please use the option that is best for your users:

  • Email: help@cortex.io, or open a support ticket in the in app Resource Center
  • Chat: Available in the Resource Center
  • Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your customer success manager.