Protecting Azure AD SSO with SGNL


Protected Systems are applications, services, or infrastructure that you want to protect with SGNL. In this guide, we’ll describe how to achieve fine-grained access control at sign-in time with Azure AD and SGNL, enabling the right amount of access to applications and infrastructure connected to Azure AD.

With this integration, Azure AD need not know about the policies, systems of record, or any of the data in SGNL - it simply needs to pass to SGNL:

  • Who/What is requesting the access (The Principal)
  • (Optional) What is attempting to be accessed (The Asset)
  • (Optional) What operation is being attempted on the asset (The Action)
  • An access token that ensures the Protected System is a legitimate caller into SGNL


  • An Azure AD Tenant
  • A SGNL Client
  • A SGNL User Account with Admin privileges
  • At least 1 Azure AD system of record integrated to SGNL, containing principals and (optionally) assets that will be evaluated in access evaluations
  • (Optional) 1 or more policies that you want assigned to the integration

Creating a Protected System in SGNL

  1. Log-In to your SGNL Client with an Admin Account
  2. From the left navigation pane, select Protected Systems and Add, or simply click Add from the SGNL Dashboard
  3. Select ‘Azure AD’ from the Identity Providers category in the list of integrations
  4. Give your integration a descriptive display name and description
  5. Specify the Default Policy to be applied to your App
    • Allow: If no policies provide a decision for an access request, SGNL will respond to the access request with an Allow decision
    • Deny: If no policies provide a decision for an access request, SGNL will respond to the access request with a Deny decision
  6. Next, you’ll need to configure which identifier Azure AD is using to describe your user/principal
    • This is likely your Azure AD user’s email address or login name. This should be in the format of the Principal ID of the user that will request access to the Protected System.
    • e.g. If an Azure AD user will be requesting access to this Protected System with the Principal ID as their login name, the principal identifier should be the Azure AD principal name.
  7. You’ll also need to define the identifiers for the types of Assets that you are looking to protect
    • This might be app identifiers sourced directly from Azure AD, or something more granular within one of your other Systems of Record
  8. Once configured, click Continue to save your configuration and move on to other configuration steps

Configuring Authentication

  1. Authentication ensures that only authorized systems can make requests into SGNL, as well as verifying the identity of an integration in order to effectively evaluate Policies - to access Authentication settings, open your AWS protected system and select the Authentication tab

    SGNL - Authentication

  2. Click Generate Token

  3. Give your token a descriptive name so that you know how it’s being used in the future and click to Generate Token

    SGNL - Generate Token

  4. On the next screen, copy the token - this will be used by Azure AD to make access requests to SGNL using the SGNL Access Service API

    Note: The value of this token is not available again after this screen, so ensure you securely store it for steps later in this guide

    SGNL - Token

Integrating Azure AD Custom Authentication Extensions with SGNL

Integrating SGNL with Azure AD, for the purposes of securing SSO, relies on Azure AD Custom Authentication Extensions. Azure AD Custom Authentication Extensions enable Azure AD to make an outbound request that can be routed to SGNL, in order to determine whether a user should have access to a specific application at that point in time, or what roles, claims, or tags to include in their token.

The steps to configure SGNL with Azure AD SSO are fairly straightforward. Azure includes a great guide for configuring Custom Authentication Extensions. You’ll need a custom claim provider API endpoint to get started, the good news is that this can be easily deployed with our out of box connector, or code that you create inside of Azure Functions or Container Apps - a sample is included below:

#r "Newtonsoft.Json"
using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System;
using System.IO;
using System.Text;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);

    // Extract the relevant query fields from the request body
    string principalId = data?.data.authenticationContext.user.userPrincipalName;
    string ipAddress = data?.data.authenticationContext.client.ip;
    string assetId = data?.data.authenticationContext.clientServicePrincipal.appDisplayName;

    // Read the correlation ID from the Azure AD  request    
    string correlationId = data?.data.authenticationContext.correlationId;

    // Optional claims to return to Azure AD
    ResponseContent r = new ResponseContent();[0].claims.CorrelationId = correlationId;[0].claims.ApiVersion = "1.0.0";[0].claims.DateOfBirth = "05/08/1984";[0].claims.CustomRoles.Add("Reader");[0].claims.CustomRoles.Add("Admin");

    // Create a request for the SGNL Access API 
    WebRequest request = WebRequest.Create("");

    request.Method = "POST";
    // TODO: Do this elegantly…
    string postData = "{\"principal\":{\"id\":\"" + principalId + "\",\"ipAddress\":\"" + ipAddress  + "\"},\"queries\":[{\"action\":\"access\",\"assetId\":\"" + assetId + "\"}]}"
    byte[] byteArray = Encoding.UTF8.GetBytes(postData);
    // Set the ContentType property of the WebRequest.
    request.ContentType = "application/json";
    request.Headers["Authorization"] = "Bearer eyJk..5MzkwIn0=";
    // Get the request stream
    Stream dataStream = request.GetRequestStream();
    dataStream.Write(byteArray, 0, byteArray.Length);
    // Get the response
    WebResponse response = request.GetResponse();
    dataStream = response.GetResponseStream();
    StreamReader reader = new StreamReader(dataStream);
    // Read the content
    string responseFromServer = reader.ReadToEnd();
    dynamic responseData = JsonConvert.DeserializeObject(responseFromServer);
    string decision = responseData?.decisions[0].decision;
    // Return a decision to the app
    if (decision == "Allow") {
        return new OkObjectResult(r);
    else {
        return new BadRequestObjectResult("Access was Denied :-(");

public class ResponseContent{
    public Data data { get; set; }
    public ResponseContent()
        data = new Data();

public class Data{
    public string odatatype { get; set; }
    public List<Action> actions { get; set; }
    public Data()
        odatatype = "microsoft.graph.onTokenIssuanceStartResponseData";
        actions = new List<Action>();
        actions.Add(new Action());

public class Action{
    public string odatatype { get; set; }
    public Claims claims { get; set; }
    public Action()
        odatatype = "microsoft.graph.tokenIssuanceStart.provideClaimsForToken";
        claims = new Claims();

public class Claims{
    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string CorrelationId { get; set; }
    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string DateOfBirth { get; set; }
    public string ApiVersion { get; set; }
    public List<string> CustomRoles { get; set; }
    public Claims()
        CustomRoles = new List<string>();

Once you’ve got a Custom Claim Extension endpoint deployed, you’ll need to register the Custom Extension in the Azure Portal.

The final step, you should now assign the Custom Extension to one or more of your Enterprise Applications in the Azure Portal, from the Sign-On tab and grant Admin Consent, and that’s it.

At this point, it’s likely that all decisions will either be Allow or Deny, based on the Default Decision you’ve selected for the Azure AD Integration - if that’s the case, you’re ready to start assigning policies.

Assigning Policies

  1. Once the Azure AD integration is created, you can start assigning versions of Policies - to get started, select Policies from the tabs in your newly created integration

    SGNL - Policies

  2. Select ‘Assign Policies’

  3. Select:

    • The Policies you want to apply to the integration with the check box
    • The version of the Policy you want applied

    SGNL - Select Policies

  4. Click Next once you have the Policies and Versions configured as is appropriate

  5. Select the Enforcement mode for the Policies you chose in the previous step

    • Simulated: Policy Versions that are being simulated will only log their access decision in the SGNL logs and will not impact the access decision that SGNL hands back to an integration. Simulated policies are useful for performing what-if analysis of new policy versions as well as debugging policy changes.

      Note: It’s considered best practice to start with policies in Simulated mode, to verify that policies have been created an applied as expected

    • Enforced: Policy Versions that are being enforced will impact the access decisions that SGNL hands back to an integration. Enforced Policies will determine access for an integration

    SGNL - Set Enforcement

  6. Select your desired Enforcement mode and select Assign

  7. Versions of Policies will now be Assigned to your integration

    SGNL - Policy Assignments