Skip to content

Commit

Permalink
fix: updating integration guides for oauth
Browse files Browse the repository at this point in the history 
Signed-off-by: Russ Savage <[email protected]>
  • Loading branch information
@russorat
russorat committed Jan 10, 2025
1 parent 737367d commit 34bd743
Show file tree
Hide file tree
Showing 27 changed files with 373 additions and 322 deletions.
48 changes: 5 additions & 43 deletions docs/integrations/amazon/oauth.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
description: Authenticate users with Amazon OAuth
---

import ConfigExample from "/src/components/ConfigExample.tsx";
import Amazon from "/traffic-policy/actions/oauth/examples/custom-amazon-example.mdx";
import Email from "/traffic-policy/actions/oauth/examples/restrict-by-email-example.mdx";

# Amazon OAuth

Expand All @@ -26,57 +27,18 @@ The step-by-step instructions below follow Amazon's documentation on [Register f
5. On the **Security Profile** page, click **Edit**, enter `https://idp.ngrok.com/oauth2/callback` in the **Allowed Return URLs** field, and then click **Save**.
![](/img/howto/oauth/2-amazon-register.png)

### Update your ngrok endpoint configuration
### Update your ngrok endpoint traffic policy

1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt&orderBy=desc) 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:

<ConfigExample
snippetText={null}
showLineNumbers={true}
yamlMetastring="{4-10}"
jsonMetastring="{5-15}"
config={{
on_http_request: [
{
actions: [
{
type: "oauth",
config: {
provider: "amazon",
client_id: "{your app's OAuth client id}",
client_secret: "{your app's OAuth client secret}",
scopes: ["profile"],
},
},
],
},
],
}}
/>
<Amazon />

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

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

<ConfigExample
snippetText="Only allow access to [email protected]. Add this after your OAuth Action."
showLineNumbers={true}
config={{
on_http_request: [
{
expressions: [
"!(actions.ngrok.oauth.identity.email in ['[email protected]'])",
],
actions: [
{
type: "deny",
},
],
},
],
}}
/>
<Email />

### Additional application setup information

Expand Down
27 changes: 19 additions & 8 deletions docs/integrations/facebook/oauth.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
description: Authenticate users via Facebook OAuth
---

import Facebook from "/traffic-policy/actions/oauth/examples/custom-facebook-example.mdx";
import Email from "/traffic-policy/actions/oauth/examples/restrict-by-email-example.mdx";

# Facebook OAuth

## Creating a custom Facebook application
Expand Down Expand Up @@ -35,15 +38,23 @@ For additional assistance, see the [Facebook app registration](https://developer
15. Select the toggle for "In development" at the top of the page and confirm switching to live mode.
16. Your application should now show as live: ![](/img/howto/oauth/6-facebook-live.png)

### Update your endpoint configuration
### Update your ngrok Endpoint Traffic Policy

1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt&orderBy=desc) 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:

<Facebook />

A Note about Scopes: You may add [any scopes](https://developers.facebook.com/docs/apps/review/login-permissions) that are required by your application with the following caveats.

- Scopes which require a Facebook [app review](https://developers.facebook.com/docs/apps/review/#app-review) are unsupported.
- ngrok will enforce that users [accept all permissions](https://developers.facebook.com/docs/facebook-login/handling-declined-permissions#reprompt) before completing authorization.

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

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

1. Return to the ngrok dashboard and create or edit an OAuth edge configuration module.
2. Choose to use your own application with Facebook as the provider.
3. Include the app ID and app secret that were stored earlier.
4. Add [any scopes](https://developers.facebook.com/docs/apps/review/login-permissions) required by your application.
- Scopes which require a Facebook [app review](https://developers.facebook.com/docs/apps/review/#app-review) are unsupported.
- ngrok will enforce that users [accept all permissions](https://developers.facebook.com/docs/facebook-login/handling-declined-permissions#reprompt) before completing authorization.
5. Add the `email` scope if it is not already present.
<Email />

### Additional application setup information

Expand Down
52 changes: 11 additions & 41 deletions docs/integrations/github/oauth.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
description: Authenticate users via GitHub OAuth
---

import Github from "/traffic-policy/actions/oauth/examples/custom-github-example.mdx";
import Name from "/traffic-policy/actions/oauth/examples/restrict-by-name-example.mdx";

# GitHub OAuth

## Creating a custom GitHub OAuth application
Expand All @@ -10,53 +13,20 @@ description: Authenticate users via GitHub OAuth
2. Set the Authorization callback URL to `https://idp.ngrok.com/oauth2/callback`.
3. Submit the form. A working example registration: ![](/img/howto/oauth/1-github-register.png)
4. Save the client ID and client secret from the application overview: ![](/img/howto/oauth/2-github-client_id_and_secret.png)
5. Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module. You do this by [going to your edges](https://dashboard.ngrok.com/cloud-edge/edges), clicking on the edge that you want to apply OAuth to, and selecting the OAuth tab within edge your routes. From there you will be prompted to begin setup.
6. Choose to use your own application with GitHub as the provider.
7. Include the client ID and secret from earlier.
8. Add any scopes your application requires.
- Include the `read:user` scope (or more permissive, like `user`) for ngrok.
9. Add any team or organization constraints by the their mention handle(s), excluding the `@` prefix.
- For example, the [ngrok](https://github.com/ngrok) organization's mention handle is `@ngrok`, so the organization constraint would be `ngrok`. Similarly, the `@ngrok/developers` team would be matched by the constraint `ngrok/developers`.
- If a constraint is specified, the `read:org` scope is required. A more permissive scope, such as `org`, also works.
- Organizations must allow [third-party access](#using-organization-and-teams) to your app.

## Additional GitHub headers provided by ngrok

In addition to the headers set for every OAuth provider, these additional headers are available when using GitHub.

`ngrok-auth-github-user-id`

The username of the authorized user.

`ngrok-auth-github-organization`

**Only when a team or organization constraint matches:** the [first matching](#header-presence-and-constraint-ordering) GitHub organization's mention handle (e.g "coreutils").

`ngrok-auth-github-team`

**Only when a team constraint matches:** the [first matching](#header-presence-and-constraint-ordering) GitHub team mention handle (e.g "coreutils/contributors").

## Using Organization and Teams

To authorize users based on organization or team membership, the organization must allow third party access. There are multiple ways to grant access:

- Organizations may allow unrestricted third-party access from settings.
- Owners can grant access to an application during authorization.
- Members can request access as part of authorization.
- Members can [request access from settings.](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/requesting-organization-approval-for-oauth-apps)
### Update your ngrok endpoint traffic policy

The ngrok managed application can authorize users based on organization or team. **For organizations concerned about membership privacy, your own application should always be used**. When granting third-party access to the managed application, anyone using the managed application may constrain based on your organization's membership.
1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt&orderBy=desc) 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:

## Header presence and constraint ordering
<Github />

Organization and team headers are present only when an organization or team constraint matches. For example, an endpoint constrained solely on the `ngrok` organization will always have authorized users with the `ngrok` organization header. An endpoint without any organization or team constraints will receive no organization or team header.
3. Click **Save** to validate and update your traffic policy.

ngrok authorizes against users' first 200 memberships of each constraint in chronological order of the team or organization's creation. Headers are filled from the first user data match in order:
4. Optionally, configure access control to your service by only allowing specific users or domains.

1. From any team membership, check the parent organization.
2. Check team membership.
3. Check organization membership.
<Name />

## Known Limitations

- Users who utilize GitHub's [private email setting](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#:~:text=If%20you%27d%20like%20to%20keep%20your%20personal,to%20Keep%20my%20email%20address%20private.) are not able to sign in.
- Users who utilize GitHub's [private email setting](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#:~:text=If%20you%27d%20like%20to%20keep%20your%20personal,to%20Keep%20my%20email%20address%20private) are not able to sign in.
16 changes: 12 additions & 4 deletions docs/integrations/gitlab/oauth.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
description: Authenticate users via GitLab OAuth
---

import Gitlab from "/traffic-policy/actions/oauth/examples/custom-gitlab-example.mdx";
import Email from "/traffic-policy/actions/oauth/examples/restrict-by-email-example.mdx";

# GitLab

## Configure GitLab OAuth with ngrok
Expand All @@ -22,13 +25,18 @@ The step-by-step instructions below follow GitLab's documentation on [setting up

![](/img/howto/oauth/2-gitlab-scopes.png)

### Update your ngrok edge configuration
### Update your ngrok endpoint traffic policy

1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt&orderBy=desc) 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:

<Gitlab />

1. Access the [ngrok Dashboard](https://dashboard.ngrok.com/), sign in, create or edit an edge, and click **OAuth** to enable the OAuth configuration.
3. Click **Save** to validate and update your traffic policy.

2. Select **GitLab** in the **Identity Provider** selector and then enter the **Client ID** and **Client Secret** values you copied previously in the corresponding fields.
4. Optionally, configure access control to your service by only allowing specific users or domains.

3. Click **Save**.
<Email />

### Additional application setup information

Expand Down
21 changes: 14 additions & 7 deletions docs/integrations/google/oauth.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
description: Authenticate users with Google OAuth
---

import Google from "/traffic-policy/actions/oauth/examples/custom-google-example.mdx";
import Email from "/traffic-policy/actions/oauth/examples/restrict-by-email-example.mdx";

# Google OAuth

## Creating a custom Google OAuth application
Expand Down Expand Up @@ -31,14 +34,18 @@ Step-by-step instructions below follow Google's documentation on [setting up OAu
4. Name your secret, then set "Authorized Redirect URIs" to `https://idp.ngrok.com/oauth2/callback`. The final credentials form should resemble: ![](/img/howto/oauth/2-google-create_client_id.png)
5. Securely store the client ID and secret from the final screen: ![](/img/howto/oauth/3-google-client_id_and_secret.png)

### Update your endpoint configuration
### Update your ngrok endpoint traffic policy

1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt&orderBy=desc) 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:

<Google />

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

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

1. Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module for your edge.
2. Choose to use your own application with Google as the provider.
3. Include the client ID, secret, and scopes configured in your application.
4. Add the following scopes to your application if they are not already present:
- `https://www.googleapis.com/auth/userinfo.profile`
- `https://www.googleapis.com/auth/userinfo.email`
<Email />

### Additional application setup information

Expand Down
16 changes: 10 additions & 6 deletions docs/integrations/linkedin/oauth.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
description: Authenticate users with LinkedIn OAuth
---

import Linkedin from "/traffic-policy/actions/oauth/examples/custom-linkedin-example.mdx";
import Email from "/traffic-policy/actions/oauth/examples/restrict-by-email-example.mdx";

# LinkedIn

## Creating a custom LinkedIn OAuth application
Expand All @@ -24,17 +27,18 @@ The step-by-step instructions below follow LinkedIn's documentation on [setting

![](/img/howto/oauth/2-linkedin-add-products.png)

### Update your endpoint configuration
### Update your ngrok endpoint traffic policy

1. Access the [ngrok Dashboard](https://dashboard.ngrok.com/), sign in, create or edit an edge, and click **OAuth** to enable the OAuth configuration.
1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt&orderBy=desc) 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:

2. Select **LinkedIn** in the **Identity Provider** selector, and select **Use my own OAuth application** in the **OAuth Application** field.
<Linkedin />

**Note**: Alternatively, you can select **Use an ngrok-managed OAuth application**. If so, there is no need to create an application in the LinkedIn developer portal.
3. Click **Save** to validate and update your traffic policy.

3. Enter the **Client ID** and **Client Secret** values you copied previously in the corresponding fields and then click **Save** to save the edge configuration.
4. Optionally, configure access control to your service by only allowing specific users or domains.

4. Access your application using the link provided by the **Endpoints** URL of your edge.
<Email />

### Additional application setup information

Expand Down
18 changes: 14 additions & 4 deletions docs/integrations/microsoft/oauth.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
description: Authenticate users with Azure AD OAuth
---

import Microsoft from "/traffic-policy/actions/oauth/examples/custom-microsoft-example.mdx";
import Email from "/traffic-policy/actions/oauth/examples/restrict-by-email-example.mdx";

# Microsoft OAuth

## Creating a custom Microsoft OAuth application
Expand Down Expand Up @@ -34,11 +37,18 @@ Step-by-step instructions below closely follow [Microsoft documentation](https:/
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: ![](/img/howto/oauth/4-microsoft-client_secret.png)

### Update your endpoint configuration
### Update your ngrok endpoint traffic policy

1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt&orderBy=desc) 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:

<Microsoft />

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

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

1. Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module.
2. Choose to use your own application with Microsoft as the provider.
3. Include the scopes, client ID, and client secret for your application.
<Email />

### Additional application setup information

Expand Down
16 changes: 10 additions & 6 deletions docs/integrations/twitch/oauth.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
description: Authenticate users with Twitch OAuth
---

import Twitch from "/traffic-policy/actions/oauth/examples/custom-twitch-example.mdx";
import Email from "/traffic-policy/actions/oauth/examples/restrict-by-email-example.mdx";

# Twitch

## Creating a custom Twitch OAuth application
Expand All @@ -22,17 +25,18 @@ The step-by-step instructions below follow Twitch's documentation on [Using OAut

![](/img/howto/oauth/1-twitch-register.png)

### Update your endpoint configuration
### Update your ngrok endpoint traffic policy

1. Access the [ngrok Dashboard](https://dashboard.ngrok.com/), sign in, create or edit an edge, and click **OAuth** to enable the OAuth configuration.
1. Access the [ngrok Dashboard Endpoints page](https://dashboard.ngrok.com/endpoints?sortBy=createdAt&orderBy=desc) 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:

2. Select **Twitch** in the **Identity Provider** selector, and select **Use my own OAuth application** in the **OAuth Application** field.
<Twitch />

**Note**: Alternatively, you can select **Use an ngrok-managed OAuth application**. If so, there is no need to create an application in the Twitch developer console.
3. Click **Save** to validate and update your traffic policy.

3. Enter the **Client ID** and **Client Secret** values you copied previously in the corresponding fields and then click **Save** to save the edge configuration.
4. Optionally, configure access control to your service by only allowing specific users or domains.

4. Access your application using the link provided by the **Endpoints** URL of your edge.
<Email />

### Additional application setup information

Expand Down
3 changes: 3 additions & 0 deletions docs/traffic-policy/actions/oidc.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import ActionBehavior from "/traffic-policy/actions/oidc/behavior.mdx";
import ActionConfig from "/traffic-policy/actions/oidc/config.mdx";
import ActionExamples from "/traffic-policy/actions/oidc/examples/index.mdx";
import ActionOverview from "/traffic-policy/actions/oidc/index.mdx";
import Pricing from "/traffic-policy/actions/oidc/pricing.mdx";
import ActionVariables from "/traffic-policy/actions/oidc/variables.mdx";
import ActionVariablesDescription from "/traffic-policy/common/action-variables-description.mdx";

Expand All @@ -16,3 +17,5 @@ import ActionVariablesDescription from "/traffic-policy/common/action-variables-

<ActionVariablesDescription />
<ActionVariables />

<Pricing />
10 changes: 10 additions & 0 deletions docs/traffic-policy/variables/action.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import BasicAuth from "/traffic-policy/actions/basic-auth/variables.mdx";
import CompressResponse from "/traffic-policy/actions/compress-response/variables.mdx";
import JwtValidation from "/traffic-policy/actions/jwt-validation/variables.mdx";
import Log from "/traffic-policy/actions/log/variables.mdx";
import OAuth from "/traffic-policy/actions/oauth/variables.mdx";
import OIDC from "/traffic-policy/actions/oidc/variables.mdx";
import RateLimit from "/traffic-policy/actions/rate-limit/variables.mdx";
import Redirect from "/traffic-policy/actions/redirect/variables.mdx";
import RemoveHeaders from "/traffic-policy/actions/remove-headers/variables.mdx";
Expand Down Expand Up @@ -40,6 +42,14 @@ import VerifyWebhook from "/traffic-policy/actions/verify-webhook/variables.mdx"

<Log />

### OAuth

<OAuth />

### OpenID Connect (OIDC)

<OIDC />

### Rate Limit

<RateLimit />
Expand Down
Loading

0 comments on commit 34bd743

Please sign in to comment.