Microsoft OAuth

Creating a custom Microsoft OAuth application

Step-by-step instructions below closely follow Microsoft documentation to create a new application for ngrok within the Azure portal.

Register an application

1. Sign-in to the Azure portal then select or create a tenant for your application.
2. Search for "Azure Active Directory" 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 Azure AD directory - Multitenant)
   • Accounts in any organizational directory (Any Azure AD 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:

YAML

---
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

JSON

{
  "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"
            ]
          }
        }
      ]
    }
  ]
}

3. Click Save to validate and update your traffic policy.

Configure access control

Optionally, configure access control to your service by only allowing specific users or domains. For example:

YAML

# Only allow access to me@example.com. Add this after your OAuth Action.
---
on_http_request:
  - expressions:
      - "!(actions.ngrok.oauth.identity.email in ['me@example.com'])"
    actions:
      - type: deny

JSON

// Only allow access to me@example.com. Add this after your OAuth Action.
{
  "on_http_request": [
    {
      "expressions": [
        "!(actions.ngrok.oauth.identity.email in ['me@example.com'])"
      ],
      "actions": [
        {
          "type": "deny"
        }
      ]
    }
  ]
}

Additional application setup information

• Creating an Azure AD tenant
• Permissions and consent (restricted permissions)
• Graph API User object properties (id, displayName, and mail/userPrincipalName)