{"id":28248113,"url":"https://github.com/ronaldbosma/protect-apim-with-oauth","last_synced_at":"2026-03-07T13:07:25.919Z","repository":{"id":292301595,"uuid":"980450439","full_name":"ronaldbosma/protect-apim-with-oauth","owner":"ronaldbosma","description":"An azd template using Bicep to demonstrate how to secure an API in Azure API Management with OAuth. It includes examples for deploying app registrations in Entra ID using Bicep.","archived":false,"fork":false,"pushed_at":"2026-03-01T17:26:18.000Z","size":816,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-01T19:42:04.238Z","etag":null,"topics":["api-management","azd","azure","azure-integration-services","bicep","oauth"],"latest_commit_sha":null,"homepage":"","language":"Bicep","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ronaldbosma.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-09T06:36:31.000Z","updated_at":"2026-03-01T17:26:19.000Z","dependencies_parsed_at":"2025-08-01T09:20:58.769Z","dependency_job_id":"1b253af1-dd0a-46bd-aeaf-dc043a967b74","html_url":"https://github.com/ronaldbosma/protect-apim-with-oauth","commit_stats":null,"previous_names":["ronaldbosma/protect-apim-with-oauth"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ronaldbosma/protect-apim-with-oauth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldbosma%2Fprotect-apim-with-oauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldbosma%2Fprotect-apim-with-oauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldbosma%2Fprotect-apim-with-oauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldbosma%2Fprotect-apim-with-oauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ronaldbosma","download_url":"https://codeload.github.com/ronaldbosma/protect-apim-with-oauth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ronaldbosma%2Fprotect-apim-with-oauth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30214711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T12:15:00.571Z","status":"ssl_error","status_checked_at":"2026-03-07T12:15:00.217Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-management","azd","azure","azure-integration-services","bicep","oauth"],"created_at":"2025-05-19T11:13:00.154Z","updated_at":"2026-03-07T13:07:25.907Z","avatar_url":"https://github.com/ronaldbosma.png","language":"Bicep","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Protect API Management with OAuth\n\nAn Azure Developer CLI (`azd`) template using Bicep to demonstrate how to secure an API in Azure API Management with OAuth.\nIt includes examples for deploying app registrations in Entra ID using Bicep.\n\n## Overview\n\nThis template deploys the following resources:\n\n![Overview](images/diagrams-overview.png)\n\nThe template creates an API Management service with an OAuth-protected API.\nIt also deploys three Entra ID app registrations using the [Microsoft Graph Bicep Extension](https://learn.microsoft.com/en-us/community/content/microsoft-graph-bicep-extension): one app registration that represents the APIs in API Management, one client with 'read' and 'write' permissions and one client with no API access (for testing authorization failures).\n\nAdditionally, Application Insights and Log Analytics Workspace are deployed for monitoring and logging purposes.\nA Key Vault is also included to securely store client secrets for integration tests.\n\nWant to learn more about how this template works? Check out the accompanying blog post [Protect APIs in Azure API Management with OAuth](https://ronaldbosma.github.io/blog/2025/09/16/protect-apis-in-azure-api-management-with-oauth/).\n\nIf you want to learn more about calling OAuth-Protected APIs from or on Azure API Management, check out the following resources:\n\n- [Call API Management with Managed Identity](https://github.com/ronaldbosma/call-apim-with-managed-identity)\n- [Call API Management backend with OAuth](https://github.com/ronaldbosma/call-apim-backend-with-oauth)\n\n\u003e [!IMPORTANT]  \n\u003e This template is not production-ready; it uses minimal cost SKUs and omits network isolation, advanced security, governance and resiliency. Harden security, implement enterprise controls and/or replace modules with [Azure Verified Modules](https://azure.github.io/Azure-Verified-Modules/) before any production use.\n\n## Getting Started\n\n### Prerequisites\n\nBefore you can deploy this template, make sure you have the following tools installed and the necessary permissions.\n\n**Required Tools:**\n\n- [Azure Developer CLI (azd)](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd)  \n  Installing `azd` also installs the following tools:\n  - [GitHub CLI](https://cli.github.com)\n  - [Bicep CLI](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install)\n- This template includes several hooks that run at different stages of the deployment process and require the following tools. For more details, see [Hooks](#hooks).\n  - [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell)\n  - [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)\n\n**Required Permissions:**\n\n- You need **Owner** permissions, or a combination of **Contributor** and **Role Based Access Control Administrator** permissions on an Azure Subscription to deploy this template.\n- You need **Application Administrator** or **Cloud Application Administrator** permissions to register the Entra ID app registrations.\n  _(You already have enough permissions if 'Users can register applications' is enabled in your Entra tenant.)_\n\n**Optional Prerequisites:**\n\nTo build and run the [integration tests](#integration-tests) locally, you need the following additional tools:\n\n- [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)\n\n### Deployment\n\nOnce the prerequisites are installed on your machine, you can deploy this template using the following steps:\n\n1. Run the `azd init` command in an empty directory with the `--template` parameter to clone this template into the current directory.\n\n   ```cmd\n   azd init --template ronaldbosma/protect-apim-with-oauth\n   ```\n\n   When prompted, specify the name of the environment, for example, `oauth`. The maximum length is 32 characters.\n\n1. Run the `azd auth login` command to authenticate to your Azure subscription using the **Azure Developer CLI** _(if you haven't already)_.\n\n   ```cmd\n   azd auth login\n   ```\n\n1. Run the `az login` command to authenticate to your Azure subscription using the **Azure CLI** _(if you haven't already)_. This is required for the [hooks](#hooks) to function properly. Make sure to log into the same tenant as the Azure Developer CLI.\n\n   ```cmd\n   az login\n   ```\n\n1. Run the `azd up` command to provision the resources in your Azure subscription and Entra ID tenant. This deployment typically takes around 4 minutes to complete.\n\n   ```cmd\n   azd up\n   ```\n\n   See [Troubleshooting](#troubleshooting) if you encounter any issues during deployment.\n\n1. Once the deployment is complete, you can locally modify the application or infrastructure and run `azd up` again to update the resources in Azure.\n\n### Demo and Test\n\nThe [Demo Guide](demos/demo.md) provides a step-by-step walkthrough on how to test and demonstrate the deployed resources.\n\n### Clean up\n\nOnce you're done and want to clean up, run the `azd down` command. By including the `--purge` parameter, you ensure that the API Management service and Log Analytics workspace don't remain in a soft-deleted state, which could cause issues with future deployments of the same environment.\n\n```cmd\nazd down --purge\n```\n\n## Contents\n\nThe repository consists of the following files and directories:\n\n```\n├── .devcontainer              [ Development container configuration files ]\n├── .github\n│   └── workflows              [ GitHub Actions workflow(s) ]\n├── .vscode                    [ Visual Studio Code configuration files ]\n├── demos                      [ Demo guide(s) ]\n├── hooks                      [ AZD Hooks to execute at different stages of the deployment process ]\n├── images                     [ Images used in the README and demo guide ]\n├── infra                      [ Infrastructure As Code files ]\n│   |── functions              [ Bicep user-defined functions ]\n│   ├── modules\n│   │   ├── application        [ The protected API ]\n│   │   ├── entra-id           [ Modules for all Entra ID resources ]\n│   │   ├── services           [ Modules for all Azure services ]\n│   │   └── shared             [ Shared Bicep modules ]\n│   ├── types                  [ Bicep user-defined types ]\n│   ├── main.bicep             [ Main infrastructure file ]\n│   └── main.parameters.json   [ Parameters file ]\n├── tests\n│   ├── IntegrationTests       [ Integration tests for automatically verifying different scenarios ]\n│   └── tests.http             [ HTTP requests to test the deployed resources ]\n├── azure.yaml                 [ Describes the apps and types of Azure resources ]\n└── bicepconfig.json           [ Bicep configuration file ]\n```\n\n## Hooks\n\nThis template has several hooks that are executed at different stages of the deployment process. The following hooks are included:\n\n### Post-provision hooks\n\nThese PowerShell scripts are executed after the infrastructure resources are provisioned.\n\n- [postprovision-create-and-store-client-secrets.ps1](hooks/postprovision-create-and-store-client-secrets.ps1):\n  Currently, we can't create secrets for an app registration with Bicep.\n  This script creates a client secret for each client app registrations in Entra ID and stores it securely in Azure Key Vault.\n  If the secret for a client already exists in Key Vault, it won't create a new one.\n\n### Pre-down hooks\n\nThese PowerShell scripts are executed before the resources are removed.\n\n- [predown-remove-app-registrations.ps1](hooks/predown-remove-app-registrations.ps1):\n  Removes the app registrations created during the deployment process, because `azd` doesn't support deleting Entra ID resources yet.\n  See the related GitHub issue: https://github.com/Azure/azure-dev/issues/4724.\n  The Entra ID resources have a custom tag `azd-env-id: \u003cenvironment-id\u003e`, so we can find and delete them.\n\n## Pipeline\n\nThis template includes a GitHub Actions workflow that automates the build, deployment and cleanup process. The workflow is defined in [azure-dev.yml](.github/workflows/azure-dev.yml) and provides a complete CI/CD pipeline for this template using the Azure Developer CLI.\n\n![GitHub Actions Workflow Summary](images/github-actions-workflow-summary.png)\n\nThe pipeline consists of the following jobs:\n\n- **Build, Verify and Package**: This job sets up the build environment, validates the Bicep template and packages the integration tests.\n- **Deploy to Azure**: This job provisions the Azure infrastructure and deploys the packaged applications to the created resources.\n- **Verify Deployment**: This job runs automated [integration tests](#integration-tests) on the deployed resources to verify correct functionality.\n- **Clean Up Resources**: This job removes all deployed Azure resources.\n\n  By default, cleanup runs automatically after the deployment. This can be disabled via an input parameter when the workflow is triggered manually.\n\n  ![GitHub Actions Manual Trigger](images/github-actions-workflow-manual-trigger.png)\n\n### Setting Up the Pipeline\n\nTo set up the pipeline in your own repository, run the following command (add ` --provider azdo` if you want to create an Azure DevOps pipeline):\n\n```cmd\nazd pipeline config\n```\n\nFollow the instructions and choose **Federated Service Principal (SP + OIDC)**, as OpenID Connect (OIDC) is the authentication method used by the pipeline, and only a **service principal** can be granted the necessary permissions in Entra ID.\n\nAfter the service principal has been created:\n\n- Add the Microsoft Graph permissions **Application.ReadWrite.All** and **AppRoleAssignment.ReadWrite.All** to the app registration of the service principal, and grant admin consent for these permissions. Use the **application permissions** type, not delegated permissions type. These permissions are necessary to deploy the Entra ID resources with the Microsoft Graph Bicep Extension.\n- Assign the service principal either the **Application Administrator** or **Cloud Application Administrator** role if it's not already assigned. One of these roles is necessary for the [hooks](#hooks) to successfully remove the Entra ID resources during cleanup.\n\nFor detailed guidance, refer to:\n\n- [Explore Azure Developer CLI support for CI/CD pipelines](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/configure-devops-pipeline)\n- [Create a GitHub Actions CI/CD pipeline using the Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/pipeline-github-actions)\n\n\u003e [!TIP]\n\u003e By default, `AZURE_CLIENT_ID`, `AZURE_TENANT_ID` and `AZURE_SUBSCRIPTION_ID` are created as variables in GitHub when running `azd pipeline config`. However, [Microsoft recommends](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect) using secrets for these values to avoid exposing them in logs. The workflow supports both approaches, so you can manually create secrets and remove the variables if desired.\n\n\u003e [!NOTE]\n\u003e In the GitHub Actions workflow, the environment name in the `AZURE_ENV_NAME` variable is suffixed with `-pr{id}` for pull requests. This prevents conflicts when multiple PRs are open and avoids accidental removal of environments, because the environment name tag is used when removing resources.\n\n## Integration Tests\n\nThe project includes integration tests built with **.NET 10** that validate various scenarios through the deployed Azure services.\nThe tests implement the same scenarios described in the [Demo](./demos/demo.md) and are located in [ClientTests.cs](tests/IntegrationTests/ClientTests.cs).\nThey automatically locate your azd environment's `.env` file if available, to retrieve necessary configuration. In the [pipeline](#pipeline) they rely on environment variables set in the workflow.\n\n## Troubleshooting\n\n### API Management deployment failed because the service already exists in soft-deleted state\n\nIf you've previously deployed this template and deleted the resources, you may encounter the following error when redeploying the template. This error occurs because the API Management service is in a soft-deleted state and needs to be purged before you can create a new service with the same name.\n\n```json\n{\n  \"code\": \"DeploymentFailed\",\n  \"target\": \"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-oauth-sdc-wiyuo/providers/Microsoft.Resources/deployments/apiManagement\",\n  \"message\": \"At least one resource deployment operation failed. Please list deployment operations for details. Please see https://aka.ms/arm-deployment-operations for usage details.\",\n  \"details\": [\n    {\n      \"code\": \"ServiceAlreadyExistsInSoftDeletedState\",\n      \"message\": \"Api service apim-oauth-sdc-wiyuo was soft-deleted. In order to create the new service with the same name, you have to either undelete the service or purge it. See https://aka.ms/apimsoftdelete.\"\n    }\n  ]\n}\n```\n\nUse the [az apim deletedservice list](https://learn.microsoft.com/en-us/cli/azure/apim/deletedservice?view=azure-cli-latest#az-apim-deletedservice-list) Azure CLI command to list all deleted API Management services in your subscription. Locate the service that is in a soft-deleted state and purge it using the [purge](https://learn.microsoft.com/en-us/cli/azure/apim/deletedservice?view=azure-cli-latest#az-apim-deletedservice-purge) command. See the following example:\n\n```cmd\naz apim deletedservice purge --location \"swedencentral\" --service-name \"apim-oauth-sdc-wiyuo\"\n```\n\n### Deployment fails with BadRequest: ServiceManagementReference field is required for Update, but is missing in the request\n\nIn an enterprise environment (for tenants with Entra IDs enabled by Service Tree management), the `ServiceManagementReference` field on an application (app registration) is mandatory.\nIf you're deploying this template in such an environment, you may encounter the following error during deployment:\n\n```\nERROR: error executing step command 'provision': deployment failed: error deploying infrastructure: deploying to subscription:\n\nDeployment Error Details:\nBadRequest: ServiceManagementReference field is required for Update, but is missing in the request.\nRefer to the TSG `https://aka.ms/service-management-reference-error` for resolving the error\nGraph client request id: \u003crequest-id\u003e.\nGraph request time: 2025-11-20T12:34:56.789Z.\n\nTraceID: \u003ctrace-id\u003e\n```\n\nThis template provides an optional parameter to set the `ServiceManagementReference` field on app registrations if required by your tenant.\nUse the following command to set the `AZURE_SERVICE_MANAGEMENT_REFERENCE` environment variable in your azd environment:\n\n```cmd\nazd env set AZURE_SERVICE_MANAGEMENT_REFERENCE \u003cid\u003e\n```\n\nReplace `\u003cid\u003e` with the valid Service Tree ID.\nIf you don't provide a valid ID, the deployment will fail with the following error: `Value for ServiceManagementReference must be a valid GUID`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronaldbosma%2Fprotect-apim-with-oauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronaldbosma%2Fprotect-apim-with-oauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronaldbosma%2Fprotect-apim-with-oauth/lists"}