Skip to content

Entra ID app registration guide

This guide explains how to register SerenityGPT's AI-powered search application with your Microsoft Entra ID directory (formerly Azure Active Directory).

Prerequisites

  • An Azure subscription with administrative access to Microsoft Entra ID.
  • Familiarity with Microsoft Entra ID concepts.
  • SerenityGPT installation hostname (internal or public-facing URL where the application will be hosted).

Registering the application

You can register the application using either the Azure Portal or Azure CLI.

Using Azure Portal

  1. Sign in to the Azure Portal.
  2. Navigate to "Microsoft Entra ID" > "App registrations".
  3. Click on "New registration".
  4. Provide a name for the application (e.g., "SerenityGPT Search").

image Screenshot of Microsoft Entra ID App registration

  1. Under "Supported account types", select "Accounts in this organizational directory only (Single tenant)".
  2. In the "Redirect URI" section, select "Web" and enter: https://[your-serenitygpt-hostname]/login/aad/callback

Note

Replace [your-serenitygpt-hostname] with the actual hostname where SerenityGPT will be installed in your environment.

  1. Click "Register" to create the application.

Using Azure CLI

If you prefer using the command line, you can register the application using Azure CLI:

az ad app create --display-name "SerenityGPT Search" \
                 --web-redirect-uris "https://[your-serenitygpt-hostname]/login/aad/callback" \
                 --sign-in-audience AzureADMyOrg

Note

All steps outlined in this document can be performed using Azure CLI for automation purposes. If your organization's internal processes mandate an automated, CLI-based approach, you can derive the necessary commands from the information provided in each section of this guide. Should you require assistance in creating a fully automated setup process, please don't hesitate to contact the SerenityGPT support team for guidance tailored to your specific needs.

Configuring the application

After registration, you need to configure the application with the required permissions and claims.

  1. Navigate to your newly registered app in the Azure Portal.
  2. Go to "API permissions" and add the following permission:
  3. Microsoft Graph > User.Read (delegated)
  4. Go to "Token configuration" and add the following optional claims for ID tokens:
  5. given_name
  6. family_name
  7. email

image Screenshot of ID token claim configuration

  1. To add department information as roles in the token:
  2. Go to "Token configuration" and click "Add groups claim".
  3. Select "Security groups" and "Groups assigned to the application".
  4. Under "Customize token properties by type", select "Group ID" for ID tokens.
  5. Check the box for "Emit groups as role claims".

Tip

The goal is to have a role claim in the ID token that identifies which department an authenticated user belongs to. If this approach doesn't align with your internal AD configuration, please suggest an alternative role claim configuration and communicate that to the SerenityGPT team.

  1. To create a client secret:
  2. Go to "Certificates & secrets".
  3. Click "New client secret".
  4. Provide a description and select an expiration period according to your organization's security policies.

Note

The expiration period for client secrets should align with your internal security guidelines. SerenityGPT does not require any specific configuration for client secrets.

Retrieving necessary information

After configuration, collect the following information to provide to the SerenityGPT team:

  1. Application (client) ID: Found on the app's "Overview" page.
  2. Directory (tenant) ID: Found on the app's "Overview" page.
  3. Client secret: Visible only when you create the secret. Ensure you copy and securely store the client secret when it's first created.
  4. Redirect URI: The URL you configured earlier.
  5. Department claim configuration: Provide details on how you've configured the department claim (e.g., group ID, custom claim name).

Configuring SerenityGPT

To configure SerenityGPT with your Microsoft Entra ID information, you'll need to set the following environment variables:

AZURE_AD_TENANT_ID=<your-tenant-id>
AZURE_AD_CLIENT_ID=<your-client-id>
AZURE_AD_CLIENT_SECRET=<your-client-secret>
AZURE_AD_REDIRECT_URI=<your-configured-redirect-uri>
AZURE_AD_TENANT_CLAIM_PATH=<path-to-department-claim>

Here are examples of how to set these variables in different environments:

Tip

These variables are here as examples only. Always refer to the full instructions in the Configuration reference and Variables reference sections of this documentation when configuring SerenityGPT.

Linux

The method for setting these environment variables may vary depending on your specific deployment strategy and environment. For development or testing purposes, for example, you would place these variables in a .env file at the root of the application directory. 

export AZURE_AD_TENANT_ID=your-tenant-id
export AZURE_AD_CLIENT_ID=your-client-id
export AZURE_AD_CLIENT_SECRET=your-client-secret
export AZURE_AD_REDIRECT_URI=https://your-serenitygpt-hostname/login/aad/callback
export AZURE_AD_TENANT_CLAIM_PATH=groups

Docker

Add these environment variables to your Docker run command or docker-compose file:

version: '3'
services:
  serenitygpt:
    image: serenitygpt/search:latest
    environment:
      - AZURE_AD_TENANT_ID=your-tenant-id
      - AZURE_AD_CLIENT_ID=your-client-id
      - AZURE_AD_CLIENT_SECRET=your-client-secret
      - AZURE_AD_REDIRECT_URI=https://your-serenitygpt-hostname/login/aad/callback
      - AZURE_AD_TENANT_CLAIM_PATH=groups

Azure Container Instances

When deploying to Azure Container Instances, you can set environment variables in the Azure Portal or using Azure CLI:

az container create \
  --name serenitygpt \
  --resource-group your-resource-group \
  --image serenitygpt/search:latest \
  --environment-variables \
    AZURE_AD_TENANT_ID=your-tenant-id \
    AZURE_AD_CLIENT_ID=your-client-id \
    AZURE_AD_CLIENT_SECRET=your-client-secret \
    AZURE_AD_REDIRECT_URI=https://your-serenitygpt-hostname/login/aad/callback \
    AZURE_AD_TENANT_CLAIM_PATH=groups

Security considerations

  1. Ensure your server is configured with the minimum TLS version required by Microsoft Entra ID.
  2. Regularly rotate client secrets according to your organization's security policies.
  3. Monitor the application's usage and audit logs in Microsoft Entra ID for any suspicious activities.
  4. Consider using certificate-based authentication for enhanced security in production environments.

Verifying the configuration

After successfully configuring and restarting the application, you should observe the following:

  1. In the application logs, look for a line that says: INFO Initializing with Entra authority: https://login.microsoftonline.com/00000000-aaaa-bbbb-cccc-dddddddddddd
  2. The main login screen should now display the Microsoft Entra ID login option:

image Screenshot of SerenityGPT login screen after a successful configuration

  1. Click on the 'Sign in with your Microsoft ID' button and follow the steps to authenticate with an eligible test user. You should then be redirected back to the application as an authenticated user.

Note

New user IDs will be created for every newly authenticated Microsoft Entra ID user, resetting their search history. If required, it's possible to manually consolidate the new Microsoft Entra ID users' profiles with their previous IDs as a one-off exercise. Please contact the SerenityGPT support team for assistance with this process.

Summary

In this guide, you have:

  1. Registered a new application in Azure Active Directory for SerenityGPT.
  2. Configured the application with the necessary permissions and claims, including:
  3. User.Read permission for Microsoft Graph
  4. Optional claims for ID tokens (given_name, family_name, email)
  5. Group claims emitted as role claims to identify user departments
  6. Retrieved essential information such as client ID, tenant ID, and client secret.
  7. Learned how to configure SerenityGPT with the required Microsoft Entra ID credentials using environment variables.
  8. Understood the process for verifying the successful integration of Microsoft Entra ID with SerenityGPT.

This integration enables secure, role-based authentication for users accessing SerenityGPT's AI-powered search functionality. It allows you to leverage your existing Microsoft Entra ID infrastructure to manage access to your organization's knowledge bases through SerenityGPT.

If you encounter any issues during the setup process or have questions about customizing the integration to better fit your organization's needs, please don't hesitate to contact the SerenityGPT support team.