Skip to content

Commit

Permalink
Improved "JWT Validation Action for Auth0" page (ngrok#610)
Browse files Browse the repository at this point in the history
I modified and fixed a few things that caused confusion for me while
following the guide:

1. The configuration provided is incomplete for a traffic policy,
despite the guide asking them to

> copy the JSON example from above directly into the ngrok Dashboard.
  
Notably, it is missing the outer layers of a proper TI JSON/YAML config
such as inbound, outbound, expressions, etc. This may be confusing to
users who haven't previously used Traffic Policies. I also linked
traffic policies as a result.

2. The page doesn't clearly guide the user to the `Applications`
category after creating an API. Some confusion may incur as a result of
looking around in the `API` category for stuff like `Settings` and not
seeing the things mentioned.
3. The page only briefly mentions where to find the JWT. Both Wils and I
missed it - it's mentioned as an offhand remark above the table.

Random aside, I added a link to actions in the traffic policies index
pages since I noticed it was missing while I was there.

Verification:
![download
(53)](https://github.com/ngrok/ngrok-docs/assets/46094706/23d76df5-e912-47c2-8ef0-5b73cc37a7a0)

Copied and pasted the YAML and it seems to work. 

Tested the new actions links and they work.
  • Loading branch information
ForgoneReality authored Feb 23, 2024
1 parent 73d2700 commit 561271a
Show file tree
Hide file tree
Showing 6 changed files with 68 additions and 41 deletions.
2 changes: 2 additions & 0 deletions docs/http/traffic-policy/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,8 @@ See [expressions](./expressions) for variable and macro definitions.
If a policy's expressions are evaluated as a match against a connection, the policy's actions will be executed. If multiple actions are defined
on a policy, the actions will execute sequentially.

See [actions](./actions) for all available actions.

## Reference

### Configuration
Expand Down
Binary file added docs/integrations/auth0/img/auth0-quickstart.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 13 additions & 5 deletions docs/integrations/auth0/jwt-action.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ import { ExampleAuth0 } from "/examples/actions/jwt-validation-auth0.mdx";

The JWT Validation action can be configured to validate tokens issued from Auth0.

This is an example configuration from setting up a new API and Machine to Machine application in Auth0.
This is an example [Traffic Policy](/docs/http/traffic-policy/) configuration for setting up a new API and Machine to Machine application in Auth0.

<ExampleAuth0 />

## 0. Define your API in Auth0

If you haven't already done so, you will need to create an API in Auth0. If you've already done this, skip to the next section.
You will need to create an API in Auth0. If you've already done this, skip to the next section.

Once logged into your [Auth0 Tenant Dashboard](https://manage.auth0.com/dashboard), select `Applications > APIs`, and then click `+ Create API`.

Expand All @@ -24,15 +24,23 @@ Name your API whatever you'd like, and choose an identifier and signing algorith

Once your API is created, you can define and add scopes needed in the `Permissions` tab. These values will be populated in the `scope` claim of your JWT.

## 1. Creating a Machine to Machine application
## 1. Accessing your JWT

Upon creating your new API, Auth0 will create an associated application under `Applications > Applications` in the left navigation bar.

Navigate to your application, and click on the `Quickstart` tab. Here, you will find a signed, fully functional JWT, as well as examples of progromatically generating more in multiple languages.

![Auth0 Quickstart JWT](img/auth0-quickstart.png)

## 2. Creating a Machine to Machine application

When you create your API in Auth0, it will automatically create a new Machine to Machine Application and authorize it to use your new API. If you added additional scopes for your API, you will need to manually add them to the new application in the `Machine to Machine Applications` tab of your new API.

![Auth0 API Permissions](img/jwt-machine-to-machine.png)

If it did not create one automatically, you can create a new Machine to Machine app and select your new API when prompted.

## 2. Configuring the ngrok JWT Validation action
## 3. Configuring the ngrok JWT Validation action

You now have everything you need to configure the JWT Validation action inside of ngrok.

Expand Down Expand Up @@ -61,7 +69,7 @@ Once you've added these values, you can Save the policy and Save the Edge in ngr
```bash
curl --request GET \
--url http://your-ngrok-domain.ngrok-free.dev/ \
--header 'authorization: Bearer YOUR-FULL-JWT-HERE'
--header 'authorization: Bearer YOUR-FULL-JWT-HERE-FROM-STEP-1'
```

If you were able to see the response from your API, everything is working correctly. You can double check by sending a malformed token.
Expand Down
2 changes: 2 additions & 0 deletions docs/tcp/traffic-policy/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ If no expressions are specified on a policy rule, its actions will always take e
If a policy's expressions are evaluated as a match against a connection, the policy's actions will be executed. If multiple actions are defined
on a policy, the actions will execute sequentially.

See [actions](./actions) for all available actions.

## Reference

### Configuration
Expand Down
2 changes: 2 additions & 0 deletions docs/tls/traffic-policy/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ If no expressions are specified on a policy rule, its actions will always take e
If a policy's expressions are evaluated as a match against a connection, the policy's actions will be executed. If multiple actions are defined
on a policy, the actions will execute sequentially.

See [actions](./actions) for all available actions.

## Reference

### Configuration
Expand Down
85 changes: 49 additions & 36 deletions examples/actions/jwt-validation-auth0.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,42 +2,55 @@ import ConfigExample from "../../src/components/ConfigExample.tsx";

export const type = "jwt-validation";
export const config = {
issuer: {
allow_list: [
{
value: "https://dev-tenant-id.us.auth0.com/",
},
],
},
audience: {
allow_list: [
{
value: "https://dev-tenant-id.us.auth0.com/api/v2/",
},
],
},
http: {
tokens: [
{
type: "jwt",
method: "header",
name: "Authorization",
prefix: "Bearer ",
},
],
},
jws: {
allowed_algorithms: ["RS256"],
keys: {
sources: {
additional_jkus: [
"https://dev-tenant-id.us.auth0.com/.well-known/jwks.json",
],
},
enabled: true,
inbound: [
{
expressions: [],
name: "JWT Validation",
actions: [
{
type: "jwt-validation",
config: {
issuer: {
allow_list: [
{
value: "https://dev-tenant-id.us.auth0.com/",
},
],
},
audience: {
allow_list: [
{
value: "https://dev-tenant-id.us.auth0.com/api/v2/",
},
],
},
http: {
tokens: [
{
type: "jwt",
method: "header",
name: "Authorization",
prefix: "Bearer ",
},
],
},
jws: {
allowed_algorithms: ["RS256"],
keys: {
sources: {
additional_jkus: [
"https://dev-tenant-id.us.auth0.com/.well-known/jwks.json",
],
},
},
},
},
},
],
},
},
],
outbound: [],
};

export const ExampleAuth0 = () => (
<ConfigExample config={{ actions: [{ type, config }] }} />
);
export const ExampleAuth0 = () => <ConfigExample config={config} />;

0 comments on commit 561271a

Please sign in to comment.