Microsoft

Let users authenticate with your app by using their Microsoft account.

You can use Gloo Mesh Gateway external auth to authenticate users to your apps with other accounts that they have. In this guide, you set up Gloo Mesh Gateway to authenticate with users’ Microsoft accounts.

About

As part of your Microsoft setup, you can use Microsoft Entra ID for cloud-based identity and access management across all your Microsoft resources, such as Microsoft 365 and Azure. You can register users and applications in Entra ID to set up OIDC authentication in Gloo Mesh Gateway.

Gloo even supports distributed claims for the identity tokens that are returned. In Azure Active Directory, identity tokens can only support a user’s membership in up to 200 groups. Sometimes, user memberships exceed this limit. In such cases, the authentication fails unless you set up distributed claims. You can give Gloo Mesh Gateway the details of your app in Entra ID. Then, behind the scenes, the Gloo external auth service talks to the Microsoft Graph API to retrieve the complete identity token. You can even set up caching, so that the Graph API does not accidentally become throttled if you have many client requests.

You can set up distributed claims for both types of OAuth through an authorization code or an access token. With access token authentication, the distributed claim can be stored in a JWT. The JWT itself can also be in a header other than the expected Authorization: Bearer header, if you combine the authentication policy with a transformation policy.

Before you begin

1. Set up Gloo Mesh Gateway in a single cluster.
2. Install Bookinfo and other sample apps.

3. Configure an HTTP listener on your gateway and set up basic routing for the sample apps.

5. Get the external address of your ingress gateway. The steps vary depending on the type of load balancer that backs the ingress gateway.

   export INGRESS_GW_ADDRESS=$(kubectl get svc -n istio-ingress istio-ingressgateway -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
   echo $INGRESS_GW_ADDRESS

   Note: Depending on your environment, you might see <pending> instead of an external IP address. For example, if you are testing locally in kind or minikube, or if you have insufficient permissions in your cloud platform, you can instead port-forward the service port of the ingress gateway:

   kubectl -n istio-ingress port-forward deploy/istio-ingressgateway-main  8081

Step 1: Set up Microsoft Entra ID

To use Microsoft Entra ID as an identity provider (IdP), you must set up Entra ID and register your app.

1. If you have not already, create your user directory. For instructions, see the Microsoft Entra ID docs.

2. Create and register an app with Microsoft Entra ID. This app is used by the Gloo external auth service for authentication purposes to call the Microsoft Graph API. For instructions, see the Microsoft Entra ID docs. At a minimum, make sure that you set up and note the values of the following fields:

   • Overview > Application (client) ID: The client ID that Microsoft Entra generates. Later, you create a Kubernetes secret for the Gloo external auth service with the client ID.

     export EXTAUTH_CLIENT_ID=<client-id>
   • Overview > Directory (tenant) ID: The tenant ID for when you configure the external auth policy later.

     export EXTAUTH_TENANT_ID=<tenant-id>
   • Manage > Certificates & secrets: The client secret that Microsoft Entra generates. Later, you create a Kubernetes secret for the Gloo external auth service with the client secret.

     export EXTAUTH_SECRET=<secret>

3. Create and register another app with Microsoft Entra ID. This app represents the backing service that your users want to access, such as an httpbin app. When users access the service, Gloo Mesh Gateway handles the OIDC authorization flow and redirects them to Microsoft to authenticate. The identity token is returned upon successful authentication, per the configuration in this app. For instructions, see the Microsoft Entra ID docs. At a minimum, make sure that you set up and note the values of the following fields:

   • Overview > Application (client) ID: The client ID that Microsoft Entra generates. Later, you create a Kubernetes secret for the Gloo external auth service with the client ID.

     export HTTPBIN_APP_CLIENT_ID=<client-id>
   • Overview > Endpoints: The issuer URL for the app, which is similar to the OpenID Connect metadata document URL without the /.well-known/openid-configuration subpath.

     export HTTPBIN_APP_ISSUER_URL=https://login.microsoftonline.com/<tenant-id>/v2.0
   • Manage > Certificates & secrets: The client secret that Microsoft Entra generates. Later, you create a Kubernetes secret for the Gloo external auth service with the client secret.

     export HTTPBIN_APP_SECRET=<secret>
   • Manage > Authentication: A redirect URI to use as part of the OAuth flow that you set up later. To create a redirect URI for your web app, click Add a platform > Web. Typically, the format of the redirect URI looks similar to https://<app-url>/callback. If you do not have a custom domain for your external auth app, you might use the ingress gateway’s address for the <app-url>.
   • Manage > App roles: A default role for the app.
   • Manage > Token configuration: Add the groups claim and any other claim that you want returned in the identity token.
   • Manage > Expose an API: Add an Application ID URI. Then, use this Application ID URI to add a scope.

     export HTTPBIN_APP_SCOPE=api://<app-url>/<scope-name>

Step 2: Prepare routing for your app

Set up the routing for the app that your users want to access. The following example uses the httpbin app. You create an HTTPS listener on a virtual gateway for the httpbin app, which is the same app that you configured an app URL and redirect URI for in Microsoft Entra.

1. Create an HTTPS listener on a virtual gateway to expose that app that you want to configure external auth for. This app is the same app that you configured an app URL and redirect URI for in Microsoft Entra.

   1. Follow the HTTPS listener guide to create the TLS configuration for the HTTPS listener.

   2. For the virtual gateway, you can use a configuration similar to the following. Make sure to update the secretName if you used a different value.

      kubectl apply -f - <<EOF
      apiVersion: networking.gloo.solo.io/v2
      kind: VirtualGateway
      metadata:
        name: httpbin-ingress
        namespace: httpbin
      spec:
        listeners:
        - http: {}
          port:
            number: 443
          tls:
            mode: SIMPLE
            secretName: gw-ssl-1-secret
        - http: {}
          httpsRedirect: true
          port:
            number: 80
        workloads:
        - selector:
            labels:
              istio: ingressgateway
      EOF

2. Create a route table for the app that sets up routing rules for the app URL and redirect URI that you configured in Microsoft Entra.

   • The app URL is the ingress gateway address with the /ip matcher that is set up in the following route table.

     export APP_URL=${INGRESS_GW_ADDRESS}/ip

   • The /callback matcher is set up to match the redirect URI that you previously configured in your Microsoft Entra app.

     kubectl apply -f - <<EOF
     apiVersion: networking.gloo.solo.io/v2
     kind: RouteTable
     metadata:
       name: httpbin-ingress
       namespace: httpbin
       labels:
         expose: "true"
     spec:
       hosts:
         - '*'
       http:
       - forwardTo:
           destinations:
           - port:
               number: 8000
             ref:
               name: httpbin
               namespace: httpbin
         matchers:
         - uri:
             exact: /ip
         name: httpbin
       - forwardTo:
           destinations:
           - port:
               number: 8000
             ref:
               name: httpbin
               namespace: httpbin
         matchers:
         - uri:
             exact: /callback
         name: httpbin-callback
       virtualGateways:
         - name: httpbin-ingress
           namespace: httpbin
           cluster: $CLUSTER_NAME
       workloadSelectors: []
     EOF

Step 3: Create the secrets for the external auth service

To use Microsoft Entra ID as an identity provider (IdP), you must set up Entra ID and register your app.

1. If you have not already, create your user directory. For instructions, see the Microsoft Entra ID docs.

2. Create and register an app with Microsoft Entra ID. This app is used by the Gloo external auth service for authentication purposes to call the Microsoft Graph API. For instructions, see the Microsoft Entra ID docs. At a minimum, make sure that you set up and note the values of the following fields:

   • Overview > Application (client) ID: The client ID that Microsoft Entra generates. Later, you create a Kubernetes secret for the Gloo external auth service with the client ID.

     export EXTAUTH_CLIENT_ID=<client-id>
   • Overview > Directory (tenant) ID: The tenant ID for when you configure the external auth policy later.

     export EXTAUTH_TENANT_ID=<tenant-id>
   • Manage > Certificates & secrets: The client secret that Microsoft Entra generates. Later, you create a Kubernetes secret for the Gloo external auth service with the client secret.

     export EXTAUTH_SECRET=<secret>

3. Create and register another app with Microsoft Entra ID. This app represents the backing service that your users want to access, such as an httpbin app. When users access the service, Gloo Mesh Gateway handles the OIDC authorization flow and redirects them to Microsoft to authenticate. The identity token is returned upon successful authentication, per the configuration in this app. For instructions, see the Microsoft Entra ID docs. At a minimum, make sure that you set up and note the values of the following fields:

   • Overview > Application (client) ID: The client ID that Microsoft Entra generates. Later, you create a Kubernetes secret for the Gloo external auth service with the client ID.

     export HTTPBIN_APP_CLIENT_ID=<client-id>
   • Overview > Endpoints: The issuer URL for the app, which is similar to the OpenID Connect metadata document URL without the /.well-known/openid-configuration subpath.

     export HTTPBIN_APP_ISSUER_URL=https://login.microsoftonline.com/<tenant-id>/v2.0
   • Manage > Certificates & secrets: The client secret that Microsoft Entra generates. Later, you create a Kubernetes secret for the Gloo external auth service with the client secret.

     export HTTPBIN_APP_SECRET=<secret>
   • Manage > Authentication: A redirect URI to use as part of the OAuth flow that you set up later. To create a redirect URI for your web app, click Add a platform > Web. Typically, the format of the redirect URI looks similar to https://<app-url>/callback. If you do not have a custom domain for your external auth app, you might use the ingress gateway’s address for the <app-url>.
   • Manage > App roles: A default role for the app.
   • Manage > Token configuration: Add the groups claim and any other claim that you want returned in the identity token.
   • Manage > Expose an API: Add an Application ID URI. Then, use this Application ID URI to add a scope.

     export HTTPBIN_APP_SCOPE=api://<app-url>/<scope-name>

Step 4: Configure authentication policies

Create a Rego policy to evaluate requests for user membership in a particular group. Then, create an external auth policy that has two modules. One module sets up Microsoft as an OIDC provider, including distributed claims. The other module sets up OPA to enforce a Rego policy on the identity token that is returned from the OIDC provider.

You can set up distributed claims for both types of OAuth through an authorization code or an access token. With access token authentication, the distributed claim can be stored in a JWT. The JWT itself can also be in a header other than the expected Authorization: Bearer header, if you combine the authentication policy with a transformation policy.

1. Create an external auth server to use for your policies.

   kubectl apply -f - <<EOF
   apiVersion: admin.gloo.solo.io/v2
   kind: ExtAuthServer
   metadata:
     name: ext-auth-server
     namespace: httpbin
   spec:
     destinationServer:
       port:
         number: 8083
       ref:
         cluster: $CLUSTER_NAME
         name: ext-auth-service
         namespace: gloo-mesh
   EOF

2. Create a config map with the Rego policy that you want to enforce. For more information, see the OPA docs. The following Rego policy:

   • Sets the input state key to azure_claims. The azure_claims setting gets the groups claim values from the Microsoft OIDC claims in the token, along with any distributed claims. This way, the user can be a member of less than or more than 200 groups.
   • Iterates through all of the groups claim values.
   • Allows requests if the user is a member of the group with ID 12345-67-89-10111213. You can update this group ID value accordingly. To find your group IDs in Microsoft Entra, go to Identity > Groups > All groups, search for your group, and copy the Object Id value.

   kubectl apply -f - <<EOF
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: httpbin-rego
     namespace: httpbin
   data:
     policy.rego: |
      package test
   
      default allow = false
      allow {
         # Allow group with ID 12345-67-89-10111213
         count({i | input.state["azure_claims"]["groups"][i] == "12345-67-89-10111213"}) > 0
       }
   EOF

3. Choose from the following OAuth options.

   • Authorization code
   • Access token