Configure Azure AD

In this article, we will configure MicroPerimeter™ Security to work with Azure Authorization Service.

Prerequisites

  • You have the MicroPerimeter™ Security deployment files ready to be deployed on your Kubernetes cluster or as a standalone MicroPerimeter™ Edge system.
  • You have an active Microsoft Azure AD subscription.
  • If you haven’t installed the MicroPerimeter™Security yet, use a Quickstart or a full installation instruction.

Introduction

Azure AD offers a built-in OAuth/OIDC Authorization service capability out of the box. Even with basic Office365 subscription, you do have access to that capability. You can register your applications and utilize OAuth Access Tokens and OIDC ID tokens to control access to your protected resources.

Starting from version 2.4 Cloudentity MicroPerimeter™ Security has full support for Azure AD OAuth/OIDC Authorization service and can utilize its endpoints for access token validations.

In this article, we will present how to configure Cloudentity MicroPerimeter™Security to utilize Azure AD Authorization server.

Configuration

MicroPerimeter™ Dashboard Application registration in Azure AD

First, we need to register a new application that will be representing MicroPerimeter™ Dashboard and MicroPerimeter™ Operator. To do that you need to:

  1. Log in to the Azure Active Directory Admin Console
  2. Go the App Registration Screen
  3. Click on +New Registration
  4. Fill in basic details like
    • user-friendly name: MicroPerimeter™ Dashboard
    • select supported account types: Accounts in this organizational directory only
    • configure the redirect URL (OAuth callback URL) http(s)://hostname:port/dashboard/login/ where hostname:port is a host and port where your MicroPerimeter™ Dashboard will be accessible.
  5. After successful registration you should see the following screen:

    Register App Overview >NOTE: It’s important to note down the Application (client) ID. In our case it is d1256d6a-0055-482b-bd42-17707982b2fd

  6. Enable the Implicit flow for that application.

    By default, all newly registered application has the OAuth Implicit flow disabled. This flow is necessary for authentication to MicroPerimeter™ Dashboard and Operator. To enable that flow you need to open the application Manifest file under Manage Menu and modify following lines from

    "name": "MicroPerimeter Dashboard",
    "oauth2AllowIdTokenImplicitFlow": false,
    "oauth2AllowImplicitFlow": false

    to

    "name": "MicroPerimeter Dashboard",
    "oauth2AllowIdTokenImplicitFlow": true,
    "oauth2AllowImplicitFlow": true

    and save the file.

Add permissions to your newly register MicroPerimeter™ Security application

Additionally, you can add special permission to your application, this permission will be used to control access to MicroPerimeter™ Sidecar and will be enforced by our MicroPerimeter™ Edge to protect all API endpoints.

By default the Dashboard utilizes two permissions dashboard_read and dashboard_write, this permissions will be included as OAuth scopes after grants them during the authentication processes (assuming he/she has required access).

To do so:

  1. Create dashboard_write permission. Go to the Expose an API under Application Manage Screen and click Add a Scope and fill in the following details:

    • Scope Name: dashboard_write
    • Admin Consent Name and description
    • User Consent Name and description

    Add Scope dashboard_write

  2. Create dashboard_read permission. Go to the Expose an API under Application Manage Screen and click Add a Scope and fill in the following details:

    • Scope Name: dashboard_read
    • Admin Consent Name and description
    • User Consent Name and description

    Add Scope dashboard_write >NOTE: Please take a note of GUIDs automatically defined for each scope api:/d1123.../dashboard_read. These GUIDs will be required during the configuration of the Authorization Server settings in MicroPerimeter™ Security. The prefix before each of the scope name is an application URI API ID used to identify which scope is being requested.

  3. Add this permission to the app just registered. Go to API Permission under the Application Manage Screen and select your app and select the ones you just created.

    Add Scope dashboard_write

MicroPerimeter™ Dashboard Application Configuration

Having done that now it’s time to update the MicroPerimeter™ Security deployment/configuration files to utilize Azure AD.

MicroPerimeter™ Security for Kubernetes

For Kubernetes version of MicrPerimeter™ Security, the modification is really easy, you just need to modify the values.yaml file present in the ./kubernetes folder.

Under the dashboard configuration you will find following configuration:

dashboard:
  dashboardOAuth:
    IDENTITY_TRACING_ENABLED: false
    IDENTITY_ADDRESS: "https://idaas.cloudentity.com/admin/ui"
    IDENTITY_API_URL: "https://idaas.cloudentity.com/api"
    AUTH_ENABLED: true
    AUTH_CLIENTID: "<<PUT_APPLICATION_CLIENT_ID>>"
    AUTH_AUTHORIZATIONURI: "https://login.microsoftonline.com/<<Azure tenant ID>/oauth2/v2.0/authorize"
    AUTH_USERINFOURI: "https://login.microsoftonline.com/<<Azure tenant ID>>/openid/userinfo"
    AUTH_READSCOPENAME: "dashboard_read"
    AUTH_WRITESCOPENAME: "dashboard_write"
    AUTH_AUTHORIZEREADSCOPENAME: "<<PUT_APPLICATION_URI_API_ID>>/dashboard_read"
    AUTH_AUTHORIZEWRITESCOPENAME: "<<PUT_APPLICATION_URI_API_ID>>/dashboard_write"
    ## oauth authentication configuration for microperimeter-edge
    IDP_HOST: "login.microsoftonline.com"
    IDP_PORT: "443"
    IDP_SSL: "true"
    IDP_PATH: "/<<PUT_YOUR_TENANT_ID>>/discovery/v2.0/"
    IDP_ENDPOINT: "keys"

You need to populate it with the Application (client) ID for MicroPerimeter™ Dashboard you just registered with Azure AD and your Azure Tenant ID.

On top of it, you need to specify the Application URI API ID that is attached to the custom scopes you created in the previous step (ones starting with api:/...)

Additionally, you need to configure the location of the JWK endpoint for your Azure Tenant. This can be configured via the same values.yaml file.

edgeApiGateway:
  name: microperimeter-edge
  cloud: idaas.cloudentity.com
  ns: microperimeter-services
  idp:
    ## oauth authentication configuration for microperimeter-edge
    IDP_HOST: "login.microsoftonline.com"
    IDP_PORT: "443"
    IDP_SSL: "true"
    IDP_PATH: "/<<PUT_YOUR_TENANT_ID>>/discovery/v2.0/"
    IDP_ENDPOINT: "keys"

Where:

  • <<PUT_YOUR_TENANT_ID>> is your Azure Tenant ID.

MicroPerimeter™ Security as Edge API Gateway

In case when you are using only our MicroPerimeter™ Edge Security for protection of your traditional applications and APIs, the configuration is similar. You just need to modify the .env file present in the ./standalone folder.

In that file, you will find the following configuration.

# dashboard auth configuration
AUTH_ENABLED=true
AUTH_AUTHORIZATIONURI=https://login.microsoftonline.com/<<PUT_YOUR_TENANT_ID>>/oauth2/v2.0/authorize
AUTH_USERINFOURI=https://login.microsoftonline.com/<<PUT_YOUR_TENANT_ID>>/openid/userinfo
AUTH_CLIENTID=<<PUT_APPLICATION_CLIENT_ID>>
AUTH_REDIRECTURI=http://<<host>>:<<port>>/dashboard/login/
AUTH_READSCOPENAME=dashboard_read
AUTH_WRITESCOPENAME=dashboard_write
AUTH_AUTHORIZEREADSCOPENAME=api://<<PUT_APPLICATION_URI_API_ID>>/dashboard_read
AUTH_AUTHORIZEWRITESCOPENAME=api://<<PUT_APPLICATION_URI_API_ID>>/dashboard_write
IDENTITY_ADDRESS=https://idaas.cloudentity.com/admin/ui
IDENTITY_API_URL=https://idaas.cloudentity.com/api

Where:

  • <<PUT_YOUR_TENANT_ID>> is your Azure Tenant ID.
  • <<PUT_APPLICATION_CLIENT_ID>> is your Application (client) ID for MicroPerimeter™ Dashboard you just registered with Azure AD and your Azure Tenant ID.
  • <<PUT_APPLICATION_URI_API_ID>> is your Application URI API ID that is attached to the custom scopes you created in the previous step (ones starting with api:/...)

Additionally, you need to configure the location of the JWK endpoint for your Azure Tenant.

# oauth authentication in microperimeter-edge
IDP_HOST=login.microsoftonline.com
IDP_PORT=443
IDP_SSL=true
IDP_PATH=/<<PUT_YOUR_TENANT_ID>>/discovery/v2.0/
IDP_ENDPOINT=keys

Where <<PUT_YOUR_TENANT_ID>> is your Azure tenant ID.

MicroPerimeter™ Security installation

After adjusting the configuration of the deployment files you can deploy the MicroPerimeter™ Security following the instructions provided in the Installation guide.

Verification

After a successful deployment of the MicroPerimeter™ Security go to the Dashboard page and click on Login.

You should get redirected to the Microsoft Login screen and after successful authentication, you should be able to see the Consent screen asking you to confirm all scope grants requested by a client application.

Assuming that you provided the consent here, you will be redirected to the MicroPerimeter™ Dashboard screen.

MicroPerimeter(TM) Dashboard