Protecting Azure API Management with SGNL

Introduction

Protected Systems are applications, services, or infrastructure that you want to protect with SGNL. In this guide, we’ll enhance access control for your APIs by integrating SGNL with Azure API Management (APIM) to enable continuous access evaluations. If you’re not sure if an APIM and SGNL Integration is right for your enterprise, visit our Azure API Management (APIM) Blog Post or watch the video below to learn more.

With this integration, APIM 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

Prerequisites

An existing APIM deployment
A SGNL Client
A SGNL User Account with Admin privileges
At least 1 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

Log-In to your SGNL Client with an Admin Account
From the left navigation pane, select Protected Systems and Add, or simply click Add from the SGNL Dashboard
Select ‘Azure API Management’ from the API Gateways category in the list of integrations
Give your integration a descriptive display name and description
Specify the Default Policy to be applied to APIM
- 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
Next, you’ll need to configure which identifier APIM is using to describe your user/principal
- This may be an email address or Username that can be found in your IdP, or an EmployeeID in your HRIS system. 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 Okta user will be requesting access to this Protected System, APIM, the principal identifier should be the Okta email address.
You’ll also need to define the types of Assets that APIM is protecting
- This might be customer identifiers sourced your CRM system, or products that your customers are buying
Once configured, click Continue to save your APIM configuration and move on to other configuration steps

Configuring Authentication

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 APIM protected system and select the Authentication tab
Click Generate Token
Give your token a descriptive name so that you know how it’s being used in the future and click to Generate Token
On the next screen, copy the token - this will be used by APIM 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

Integrating Azure API Management with SGNL

The integration between Azure APIM and SGNL is based on Azure API Management inbound policies. The inbound processing policy may be configured globally for the entire API set of endpoints or on a per API operation basis.

APIM - SGNL

The Azure APIM policy expressions below shows how you can construct an SGNL authorization request with multiple authorization queries for an incoming HTTP POST request from an API consumer. This sample takes the “principal” and “accountType” key/value pairs in the incoming JSON body in addition to the HTTP request method and backend URI path. This principal, HTTP method, and account type is then used to create the authorization request to the SGNL access service. This policy results in a Deny from SGNL which then is translated to a 403 status code back to the API consumer.

Azure APIM Policy

<inbound>

<!-- Set variables for request to SGNL Access Service. The sample gets the principal from the JSBON body, HTTP method and backend URI requesed via the request object. -->
<set-variable name="principal" value="@(context.Request.Body.As<JObject>(preserveContent: true).SelectToken("principal"))" />
<set-variable name="accountType" value="@(context.Request.Body.As<JObject>(preserveContent: true).SelectToken("account.type"))" />
<set-variable name="method" value="@(context.Request.Method)" />
<set-variable name="backendUri" value="@(context.Request.Url.Path)" />

<!-- Send the authorize request to the SGNL access service. Note: We include the principal, assetId, and action in the request. -->
<send-request mode="new" response-variable-name="response" timeout="10" ignore-error="false">
<set-url>@("https://access.sgnlapis.cloud/access/v1/evaluations")</set-url>
<set-method>POST</set-method>
<!-- Set bearer token coming in from request header. This is used to call the SGNL Access Service API. -->
<set-header name="Authorization" exists-action="override">
<value>@(context.Request.Headers.GetValueOrDefault("Authorization"))</value>
</set-header>
<!-- Set additional headers for the request to the SGNL Access Service. -->
<set-header name="Content-Type" exists-action="override">
<value>application/json</value>
</set-header>
<set-header name="Accept-Encoding" exists-action="override">
<value>gzip,deflate,br</value>
</set-header>
<!-- Set the post JSON body for the request to the SGNL Access Service using the liquid template. Values can be dynamically determined or static-->
<set-body template="liquid">
{
"principal": {
"id":"{{context.Variables["principal"]}}"
},
"queries": [{
"assetId": "{{context.Variables["backendUri"]}}",
"action": "{{context.Variables["method"]}}"
},
{
"assetId": "{{context.Variables["accountType"]}}",
"action": "Create"
}
]
}
}
 </set-body>
</send-request>
<!-- Check access service resopnse. If API client is not authorized to call the API send a 401 status code. -->
<choose>
<when condition="@((int)((IResponse)context.Variables["response"]).StatusCode == 401)">
<!-- Return 401 Unauthorized -->
<return-response response-variable-name="existing response variable">
<set-status code="401" reason="SGNL Access Service - API Client Is Not Authorized" />
</return-response>
</when>
</choose>
<!-- Check access service resopnse. If Deny, then send a 403 forbidden status code to the caller. If true, APIM allows the request to continue. -->
<choose>
<when condition="@((string)((IResponse)context.Variables["response"]).Body.As<JObject>()["decisions"][0]["decision"] == "Deny")">
<!-- Return 403 Unauthorized -->
<return-response response-variable-name="existing response variable">
<set-status code="403" reason="SGNL Access Service - Not Authorized" />
</return-response>
</when>
</choose>
<choose>
<when condition="@((string)((IResponse)context.Variables["response"]).Body.As<JObject>()["decisions"][1]["decision"] == "Deny")">
<!-- Return 403 Unauthorized -->
<return-response response-variable-name="existing response variable">
<set-status code="403" reason="SGNL Access Service - Not Authorized" />
</return-response>
</when>
</choose>
<base />
</inbound>

Request Context

The following example contains a JSON document sent to a sample banking API through Azure APIM. This request is expected to open a new account with a balance of $1M. With SGNL, you can authorize the API method (GET,POST,PUT, etc.), in addition to authorizing an action on individual assets such as name, status, and account. This article shows how you can easily implement fine grained authorization for Azure APIM enabled APIs.

{
  "account": {
    "id": 774893763,
    "type": "Checking"
  },
  "name": "Alice Wu",
  "principal": "alice.wu@sgnl.ai",
  "status": "available",
  "balance": 1000000
}

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 APIM Integration - if that’s the case, you’re ready to start assigning policies.

Assigning Policies

Once the Integration is created, you can start assigning versions of Policies to the integration - to get started, select Policies from the tabs in your newly created integration
Select ‘Assign Policies’
Select:
- The Policies you want to apply to the integration with the check box
- The version of the Policy you want applied
Click Next once you have the Policies and Versions configured as is appropriate
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
Select your desired Enforcement mode and select Assign
Versions of Policies will now be Assigned to your integration