Platform overview

LKAB uses the Azure API Management service as its API Management platform. Along with the service, we also provide a CI/CD infrastructure in LKAB's Azure DevOps platform to support API-teams/-vendors with automation to publish their APIs, and make them available for consumption via the API Management service.

Scope

This document covers the Azure components and services managed by LKAB's API Management team.
The API Management platform uses other components, such as Azure Active Directory, Azure Application Gateway and Azure Firewall, to contribute to a secure infrastructure.
These components are centrally managed and are beyond the scope of this document, but are sometimes referenced to provide a complete context of the solution.

High-level overview

The core components of the Azure API Management service is:

The API gateway, where all api requests are handled through.
The API portal (also called the Developer portal), where api consumers can browse through all available APIs, review the API methods and datamodels, and learn whom to contact to request access.
(Monitoring, currently work in progress, until released we leave that out )
CI/CD Infrastructure in LKAB Azure DevOps
Onboarding process and Documentation in wiki format, in LKAB DevOps

API Management core components

Environments

To support the full lifecycle of the published APIs we provide 4 different environments (instances) of the API Management platform.

Environment	API Gateway URL	API Portal URL
Development	`https://dev.api.lomi.lkab.com`	`https://developer.dev.api.lomi.lkab.com`
Test	`https://test.api.lomi.lkab.com`	`https://developer.test.api.lomi.lkab.com`
Stage (QA)	`https://stage.api.lomi.lkab.com`	`https://developer.stage.api.lomi.lkab.com`
Production	`https://api.lomi.lkab.com`	`https://developer.api.lomi.lkab.com`

All environments are fully accessible both from public internet, and from the LKAB network (over private network).

Azure dependencies

The API Management platform uses other components, such as Azure Active Directory, Azure Application Gateway and Azure Firewall, to contribute to a secure infrastructure.
These components are centrally managed and are beyond the scope of this document, but are referenced to provide a complete context of the platform.
The image below provide an understanding of an API request passing through different components before reaching the backend API service.

API Management dependency components

The image also shows examples of APIs published through the API Management platform. Each published API's life cycle is managed by their respective "API owner",
i.e. the team or vendor that developed and provided the API to LKAB.

Security

In order for our APIs to be published publicly on the internet, we are required to comply with certain regulations, e.g. The OAuth2 authorization policy,
and use components, e.g. Web Application Firewall, to prevent intrusions.
Having said that, it is important that the respective "API owner", i.e. the API team/vendor that possesses the detailed knowledge of their API, implements with security first.

Azure Application Gateway (WAF)

Azure Application Gateway is a web traffic load balancer that enables LKAB to handle traffic to our web applications, including APIs available in the LKAB API Management platform.
The Web Application Firewall (WAF) service in Azure Application Gateway has built-in rules to prevent the most common attack patterns.
The WAF protects against the following web vulnerabilities:

SQL-injection attacks
Cross-site scripting attacks
Other common attacks, such as command injection, HTTP request smuggling, HTTP response splitting, and remote file inclusion
HTTP protocol violations
HTTP protocol anomalies, such as missing host user-agent and accept headers
Bots, crawlers, and scanners
Common application misconfigurations (for example, Apache and IIS)

Web Application Firewall has built-in rules to prevent from the most common attack patterns listed in OWASP Top Ten. These rules must be updated continuously to follow the latest attack patterns.
The current active ruleset is the OWASP 3.2, details about the ruleset can be found here: WAF Rules.
If your API requests get blocked, you should have a look at the ruleset to validate that your API client conforms to the rules defined.

Authentication and Authorization

All APIs published to the API Management platform should use OAuth2 authorization, even if the backend API uses another technique.
The provided pipeline-template has pre-defined policy templates for token verification in API Management,
and the document App registration guide - API developers describes how to create the App registration for your API.

By having a standardized authorization technology, we simplify consumption of the apis, as the api consumers can reuse the same authorization technique,
while being an established, modern and secure authorization technique.

Client requests a token from Azure AD token server.
Send the token along with the request to the API gateway.
API gateway do a brief validation of the token.
If token is valid, pass the request on to the backen api.
If the backend API implements OAuth2 authorization, it has to validate the token properly)

Auth flow
The image illustrates the request flow, both for API consumers on the public internet, as well as API consumers on LKAB network.

CI/CD Infrastructure

The API Management team provide a process, infrastructure and pipeline-templates to support automation of publishing your APIs to the API Management platform.
LKABs Azure DevOps platform is used to host the Git repositories and the pipeline runtime environment.

Process

In short, when a new API should be published for the first time:

Schedule an onboarding meeting with the API Management team, by sending an email request to api.management.team@lkab.com
Assign an API Id and agree on a suitable basepath for the API (during onboarding meeting)
Follow the guides here Publish API - Documentation home and don't hesitate to ask the API Management team for assistance if needed.
Done, your API will be accessible in the API Portal (Production)

For more details, have a look at the Publish API - Documentation home page.

Pipeline to create your OpenAPI repository

We provide a pipeline to create your OpenAPI repository. The created Git repository has 3 predefined branches, develop, release and main, to support the recommended release cycle.
The Create repository pipeline also creates service connections to Azure, and the release pipeline, to actually deploy your API specification to the API Management platform.
Each API, i.e. each OpenAPI specification, should have it's own repository.
The Git repository can be created either in the shared API Management project in Azure DevOps, or in your own Azure DevOps project (within the LKAB organization).

A guide is available here: Create repository guide

CI/CD Pipeline for your API

The repository created by the above pipeline is designed to support a GitOps workflow, for automated deployment from each branch to the corresponding API Management environment (instance), Development/Test/Stage/Production.

API Management GitOps flow

Short version of the GitOps workflow:

Create a feature branch from the develop branch.
Add OpenAPI specification
Update the environment parameters
Create a pull-request to merge the changes back to develop branch
When the pull-request is merged the pipeline will be triggered to publish to the API Management Development instance.
Review your API in API Portal (Development) and run integration testing using Postman or other tools.
When ready, create a pull-request and merge to release branch to trigger publish to the the API Management Test and Stage instance.
Repeat the review and integration testing using the Test and Stage API Management instances.
When ready to release to production, create a pull-request to the main branch to trigger publish to the API Management production environment.
Review your API and run integration testing for your Production ready API using the Production API Management instance.

You find more detailed documentation here: Publish contract first API to API Management