Microsoft OAuth

​

Creating a custom Microsoft OAuth application

​

Register an application

1. Sign-in to the Azure portal then select or create a tenant for your application.
2. Search for “Microsoft Entra ID” and select it.
3. Select “App registrations” on the left hand navigation.
4. Select “New registration” at the top.
5. Enter a name for your application.
6. ngrok does not support single tenant applications. Choose supported account types from:
   • Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant)
   • Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)
7. Choose a “Web” redirect URI and enter https://idp.ngrok.com/oauth2/callback.
8. Register your application. The final form should resemble:

​

Configure your application

1. When viewing your application, choose “Overview” on the left hand navigation.
2. Store the “Application (client) ID” in the top information section for later.
3. Select “API permissions” on the left hand navigation.
4. Add additional scopes that your application requires and store them for later.
   • Scopes which require an application review by Microsoft are unsupported.
   • Scopes that require admin consent prevent tenants’ users from authorizing until consent is granted.
5. Ensure User.Read or a more permissive scope (e.g. User.Read.All) is configured for ngrok. Example minimal configuration:
6. Choose “Certificates and Secrets” on the left hand navigation.
7. Select “New Client Secret” at the bottom, name the secret, set an expiration, and hit create.
8. Creation is asynchronous. When complete, save the secret from the “Value” column (blurred below) for later:

​

Update your ngrok endpoint traffic policy

1. Access the ngrok Dashboard Endpoints page and locate an existing endpoint you’d like to add this to or create a new one.
2. In your traffic policy, add the following configuration:

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: microsoft
          client_id: '{your app''s oauth client id}'
          client_secret: '{your app''s oauth client secret}'
          scopes:
            - openid
            - email
            - profile

​

Configure access control

on_http_request:
  - expressions:
      - '!(actions.ngrok.oauth.identity.email in [''me@example.com''])'
    actions:
      - type: deny

​

Additional application setup information

• Creating a Microsoft Entra ID tenant
• Permissions and consent (restricted permissions)
• Graph API User object properties (id, displayName, and mail/userPrincipalName)