Skip to main content
This guide explains how to add ingress to any app running in Kubernetes and restrict access to users authorized through Microsoft Entra ID (formerly Azure Active Directory), using the ngrok Kubernetes Operator. It walks you through (optionally) creating a Kubernetes cluster and example deployment, installing the Operator to route traffic through the ngrok cloud service, and using the ngrok dashboard to enable Security Assertion Markup Language (SAML) with Microsoft Entra ID as your identity provider for single sign-on. The ngrok Kubernetes Operator is ngrok’s official controller for adding secure public ingress and middleware execution to your Kubernetes apps with ngrok’s cloud service. Microsoft Entra ID is an identity and access management platform that helps administrators and DevOps engineers safeguard their organization’s multicloud environment with strong authentication and unified identity management. The Operator and Microsoft Entra ID integrate so you can route public traffic to an app on a Kubernetes cluster and restrict access to users you authorize through Microsoft Entra ID.

​
What you’ll need

  • An ngrok account.
  • A Microsoft Azure account with access to an existing Microsoft Entra ID tenant or the ability to create a new tenant with a Microsoft Entra ID P1 or P2 license.
  • A Kubernetes cluster (local or in a public cloud) with an app you want to make publicly accessible to specific users.
  • kubectl and Helm 3.0.0+ installed on your local workstation.
  • The ngrok Kubernetes Operator installed on your cluster.
  • A reserved domain from the ngrok dashboard or API; this guide refers to it as <NGROK_DOMAIN>.

​
1. Create a cluster and deploy an example app

This guide requires an app on a Kubernetes cluster (local or in a public cloud) to provide an endpoint for ngrok’s secure tunnel. For demonstration, this guide creates a local cluster with minikube and deploys the Online Boutique example. If you already have a cluster and app, skip to 2. Add the ngrok Kubernetes Operator.
  • Download the GoogleCloudPlatform/microservices-demo project to your local workstation and navigate into the new directory. 
    git clone https://github.com/GoogleCloudPlatform/microservices-demo
cd microservices-demo
  • Create a new minikube cluster. 
    minikube start -p online-boutique
  • Apply the manifests for the Online Boutique. 
    kubectl apply -f ./release/kubernetes-manifests.yaml

​
2. Add the ngrok Kubernetes Operator

Configure and deploy the ngrok Kubernetes Operator to expose your app to the public internet through the ngrok cloud service.
  • Add the ngrok Helm repository if you haven’t already. 
    helm repo add ngrok https://charts.ngrok.com
  • Create a static ngrok subdomain for ingress if you don’t have one already. Go to the Domains section of the ngrok dashboard and click Create Domain or New Domain. This static subdomain will be your NGROK_DOMAIN for the remainder of this guide. Creating a subdomain on the ngrok network provides a public route to accept HTTP, HTTPS, and TLS traffic.
  • Set up the AUTHTOKEN and API_KEY exports so Helm can install the Operator using your ngrok credentials. Find your authtoken under Your Authtoken in the ngrok dashboard. To create a new API key, go to the API section of the ngrok dashboard, click New API Key, set the description or owner, and click Add API Key. Copy the API key token from the modal before closing it; the dashboard won’t show the token again. 
    export NGROK_AUTHTOKEN=[YOUR-AUTHTOKEN]
export NGROK_API_KEY=[YOUR-API-KEY]
  • Install the ngrok Kubernetes Operator with Helm. 
    helm install ngrok-ingress-controller ngrok/kubernetes-ingress-controller \
  --namespace ngrok-ingress-controller \
  --create-namespace \
  --set credentials.apiKey=$NGROK_API_KEY \
  --set credentials.authtoken=$NGROK_AUTHTOKEN
  • Verify the health of your new Operator pod. 
    kubectl get pods -l 'app.kubernetes.io/name=kubernetes-ingress-controller'

NAME                                                              READY   STATUS    RESTARTS   AGE
ngrok-ingress-controller-kubernetes-ingress-controller-man2fg5p   1/1     Running   0          2m23s
  • Create a new boutique-ingress.yaml file that defines how the ngrok Kubernetes Operator routes traffic on your NGROK_DOMAIN to your Online Boutique app.
    Edit line 9 of the manifest below (the NGROK_DOMAIN variable) with the ngrok subdomain you created (for example, one-two-three.ngrok.app). If you’re adding the Operator to a different deployment, change metadata.name, service.name, and service.port.number to match your app. See the controller docs for spec settings and common overrides.
    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: boutique-ingress
  namespace: default
spec:
  ingressClassName: ngrok
  rules:
    - host: NGROK_DOMAIN
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend
                port:
                  number: 80
  • Apply the boutique-ingress.yaml manifest you just created. 
    kubectl apply -f boutique-ingress.yaml
    Give your cluster a few moments to launch the necessary resources and for ngrok’s cloud service to pick up the new tunnel.
    If you see an error when applying the manifest, double-check that you’ve updated the NGROK_DOMAIN value and re-apply.
  • Access your app (ingress now handled by ngrok) by navigating to your ngrok domain (for example, https://one-two-three.ngrok.app) in your browser.

​
3. Update your ngrok Edge to enable SAML

Your Kubernetes-based app is now publicly accessible through the ngrok cloud service. To restrict access to authorized users with Microsoft Entra ID credentials, enable SAML on your Edge.
  • Go to the Edges section of the ngrok dashboard and click the Edge created by the ngrok Kubernetes Operator. The domain name should match your NGROK_DOMAIN, and you should see Created by kubernetes-ingress-controller in the edge description.
  • From the Overview, click Add SAML, then Begin setup.
  • In the IdP Metadata textbox, add the following: 
    <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"></EntityDescriptor>
  • Click Save. ngrok will update your SAML configuration with SP Metadata, Entity ID, and ACS URL values; you’ll need these in the next step.

​
4. Create an enterprise app in Microsoft Entra ID

With SAML configured on your ngrok Edge, configure Microsoft Entra ID to operate as your identity provider (IdP).
  • Open your Microsoft Entra ID tenant in the Azure console.
  • Click Enterprise applications in the left-hand sidebar, then + New application, then + Create your own application. Give your app a name (for example, online-boutique) and select Integrate any other application you don’t find in the gallery (Non-gallery).
  • Click Create to create your enterprise app; you’ll be taken to its Overview dashboard.
  • To give specific users or groups access to your app, click Assign users and groups and follow the steps, then go back to Overview.
  • Click Set up single sign on so users can sign in with their Microsoft Entra credentials, then choose SAML as the single sign-on protocol.
  • Click Edit in the Basic SAML Configuration box. Copy the Entity ID from ngrok into the Identifier (Entity ID) field and the ACS URL from ngrok into the Reply URL (Assertion Consumer Service URL) field. Click Save before closing the modal.
  • In the SAML Certificates box, download the Federation Metadata XML.

​
5. Finish adding Microsoft Entra ID authorization to your ngrok Edge

Finish the SAML configuration in your ngrok dashboard.
  • Update the IdP Metadata field by clicking Upload XML and choosing the .xml file you just downloaded.
  • Click Save.

​
6. Test authorization to your app using Microsoft Entra ID

You’ve finished integrating the ngrok Kubernetes Operator and Microsoft Entra ID. Your app (the Online Boutique or a custom deployment) is now publicly accessible only to users authorized with their Microsoft Entra ID credentials.
  • Open an incognito or private browser window (or a different browser) and go to your NGROK_DOMAIN. You should see a single sign-on screen from Microsoft.
  • Enter credentials for a Microsoft account you assigned to your enterprise application in Microsoft Entra ID in step 4. Behind the scenes, ngrok requests your identity provider, Microsoft Entra ID, for authentication. Once you sign in, or are already logged in, Microsoft Entra ID then returns a SAML assertion to ngrok, telling ngrok your authentication is confirmed and you have authorization to access the app. Microsoft Entra ID will then redirect you back to your app.

​
What’s next?

You’ve now integrated the ngrok Kubernetes Operator with Microsoft Entra ID to restrict access to your app to only authenticated users. With ngrok operating as middleware, handling both ingress to your Kubernetes cluster and the handshake with Microsoft Entra ID as an identity provider, you can deploy and secure new apps in a multi-cloud environment using your existing Microsoft/Azure identity and access management settings. From an end user perspective, they only need to sign in once, using their Microsoft credentials, to authenticate themselves and access any number of applications you manage using Microsoft Entra ID. From here, you have a few options:

​
Clean up

If you created a local cluster with Minikube for the Online Boutique demo app, delete the cluster: 
minikube delete -p online-boutique
ngrok will delete your Edge automatically. To restore your previous authorization settings, open your Microsoft Entra ID tenant and delete your enterprise application.

​
Extend your ngrok Kubernetes Operator and Microsoft Entra ID integration

ngrok can manage multiple routes on a single Edge. You can configure name-based virtual hosting or route modules to secure multiple apps with single sign-on. Custom domains and a circuit breaker are good next steps for production. See the ngrok Kubernetes Operator GitHub repository and project documentation for more details.