Use Cases

Learn about different use cases for the Tenant Access Control List feature.

Block a request

This Tenant ACL rule example blocks incoming traffic from a specific geolocation country code.

Management API

To create this Tenant ACL rule with the Management API:

1. Get a Management API access token with the create:network_acls scope.

2. Call the Management API Create access control list endpoint with the following body:

{
  "description": "Example of blocking a request",
  "active": true,
  "priority": 2,
  "rule": {
    "action": {
      "block": true
    },
    "match": {
      "geo_country_codes": [
        "{geoCountryCode}"
      ]
    },
    "scope": "authentication"
  }
}{
  "description": "Example of blocking a request",
  "active": true,
  "priority": 2,
  "rule": {
    "action": {
      "block": true
    },
    "match": {
      "geo_country_codes": [
        "{geoCountryCode}"
      ]
    },
    "scope": "authentication"
  }
}

Go SDK

package main

import (
	"context"
	"log"

	"github.com/auth0/go-auth0"
	"github.com/auth0/go-auth0/management"
)

func main() {
	mgmt, err := management.New("{yourDomain}", management.WithClientCredentials("{yourClientId}", "{yourClientSecret}"))
	if err != nil {
		log.Fatal(err)
	}

	networkACL := &management.NetworkACL{
		Description: auth0.String("Example of blocking a request"),
		Active:      auth0.Bool(true),
		Priority:    auth0.Int(2),
		Rule: &management.NetworkACLRule{
			Action: &management.NetworkACLRuleAction{
				Block: auth0.Bool(true),
			},
			Match: &management.NetworkACLRuleMatch{
				GeoCountryCodes: &[]string{"{geoCountryCode}"},
			},
			Scope: auth0.String("authentication"),
		},
	}

	err = mgmt.NetworkACL.Create(context.Background(), networkACL)
	if err != nil {
		log.Fatal(err)
	}
	log.Println("Network ACL has been created")
}

Node SDK

const createNetworkAclPayload: Management.CreateNetworkAclRequestContent = {
  description: "Example of blocking a request",
  active: true,
  priority: 2,
  rule: {
    action: {
      block: true,
    },
    match: {
      geo_country_codes: ["{geoCountryCode}"],
    },
    scope: "authentication",
  },
};

const createNetworkAcl = await client.networkAcls.create(createNetworkAclPayload);

Terraform

resource "auth0_network_acl" "example_blocking_request_acl" {
    description = "Example of blocking a request"
    active = true
    priority = 2
    rule {
        action {
            block = true
        }
        match {
            geo_country_codes = ["{geoCountryCode}"]
        }
        scope = "authentication"
    }
}

Deploy CLI

networkACLs:
  - description: Example of blocking a request
    active: true
    priority: 2
    rule:
      action:
        block: true
      match:
        geo_country_codes:
          - {geoCountryCode}
      scope: authentication

Auth0 CLI

auth0 network-acl create \
    --description "Example of blocking a request" \
    --active true \
    --priority 2 \
    --rule '{"action":{"block":true},"match":{"geo_country_codes":["{geoCountryCode}"]},"scope":"authentication"}'

This is an example of a block page:

Allow a request

This Tenant ACL rule example allows traffic only from a specific geolocation country code.

Management API

To create this Tenant ACL rule with the Management API:

1. Get a Management API access token with the create:network_acls scope.

2. Call the Management API Create access control list endpoint with the following body:

{
  "description": "Example of allowing a request",
  "active": true,
  "priority": 2,
  "rule": {
    "action": {
      "allow": true
    },
    "match": {
      "geo_country_codes": [
        "{geoCountryCode}"
      ]
    },
    "scope": "authentication"
  }
}

Go SDK

package main

import (
	"context"
	"log"

	"github.com/auth0/go-auth0"
	"github.com/auth0/go-auth0/management"
)

func main() {
	mgmt, err := management.New("{yourDomain}", management.WithClientCredentials("{yourClientId}", "{yourClientSecret}"))
	if err != nil {
		log.Fatal(err)
	}

	networkACL := &management.NetworkACL{
		Description: auth0.String("Example of allowing a request"),
		Active:      auth0.Bool(true),
		Priority:    auth0.Int(2),
		Rule: &management.NetworkACLRule{
			Action: &management.NetworkACLRuleAction{
				Allow: auth0.Bool(true),
			},
			Match: &management.NetworkACLRuleMatch{
				GeoCountryCodes: &[]string{"{geoCountryCode}"},
			},
			Scope: auth0.String("authentication"),
		},
	}

	err = mgmt.NetworkACL.Create(context.Background(), networkACL)
	if err != nil {
		log.Fatal(err)
	}
	log.Println("Network ACL has been created")
}

Node SDK

const createNetworkAclPayload: Management.CreateNetworkAclRequestContent = {
  description: "Example of allowing a request",
  active: true,
  priority: 2,
  rule: {
    action: {
      allow: true,
    },
    match: {
      geo_country_codes: ["{geoCountryCode}"],
    },
    scope: "authentication",
  },
};

const createNetworkAcl = await client.networkAcls.create(createNetworkAclPayload);

Terraform

resource "auth0_network_acl" "example_allowing_request_acl" {
    description = "Example of allowing a request"
    active = true
    priority = 2
    rule {
        action {
            allow = true
        }
        match {
            geo_country_codes = ["{geoCountryCode}"]
        }
        scope = "authentication"
    }
}

Deploy CLI

networkACLs:
  - description: Example of allowing a request
    active: true
    priority: 2
    rule:
      action:
        allow: true
      match:
        geo_country_codes:
          - {geoCountryCode}
      scope: authentication

Auth0 CLI

auth0 network-acl create \
    --description "Example of allowing a request" \
    --active true \
    --priority 2 \
    --rule '{"action":{"allow":true},"match":{"geo_country_codes":["{geoCountryCode}"]},"scope":"authentication"}'

Redirect a request

This Tenant ACL rule example redirects all traffic from a specific geolocation country code.

Management API

To create this Tenant ACL rule with the Management API:

1. Get a Management API access token with the create:network_acls scope.

2. Call the Management API Create access control list endpoint with the following body:

{
  "description": "Example of redirecting a request",
  "active": true,
  "priority": 2,
  "rule": {
    "action": {
      "redirect": true,
      "redirect_uri": "REDIRECT_URI"
    },
    "match": {
      "geo_country_codes": [
        "{geoCountryCode}"
      ]
    },
    "scope": "authentication"
  }
}

Go SDK

package main

import (
	"context"
	"log"

	"github.com/auth0/go-auth0"
	"github.com/auth0/go-auth0/management"
)

func main() {
	mgmt, err := management.New("{yourDomain}", management.WithClientCredentials("{yourClientId}", "{yourClientSecret}"))
	if err != nil {
		log.Fatal(err)
	}

	networkACL := &management.NetworkACL{
		Description: auth0.String("Example of redirecting a request"),
		Active:      auth0.Bool(true),
		Priority:    auth0.Int(2),
		Rule: &management.NetworkACLRule{
			Action: &management.NetworkACLRuleAction{
				Redirect: auth0.Bool(true),
				RedirectURI: auth0.String("REDIRECT_URI"),
			},
			Match: &management.NetworkACLRuleMatch{
				GeoCountryCodes: &[]string{"{geoCountryCode}"},
			},
			Scope: auth0.String("authentication"),
		},
	}

	err = mgmt.NetworkACL.Create(context.Background(), networkACL)
	if err != nil {
		log.Fatal(err)
	}
	log.Println("Network ACL has been created")
}

Node SDK

const createNetworkAclPayload: Management.CreateNetworkAclRequestContent = {
  description: "Example of a complex comparison",
  active: true,
  priority: 1,
  rule: {
    action: {
      block: true,
    },
    match: {
      geo_country_codes: ["{geoCountryCode}"],
    },
    not_match: {
      geo_subdivision_codes: ["{geoSubdivisionCode}"],
    },
    scope: "authentication",
  },
};

const createNetworkAcl = await client.networkAcls.create(createNetworkAclPayload);

Terraform

resource "auth0_network_acl" "example_complex_comparison_acl" {
    description = "Example of a complex comparison"
    active = true
    priority = 1
    rule {
        action {
            block = true
        }
        match {
            geo_country_codes = ["{geoCountryCode}"]
        }
        not_match {
            geo_subdivision_codes = ["{geoSubdivisionCode}"]
        }
        scope = "authentication"
    }
}

Deploy CLI

networkACLs:
  - description: Example of a complex comparison
    active: true
    priority: 1
    rule:
      action:
        block: true
      match:
        geo_country_codes:
          - {geoCountryCode}
      not_match:
        geo_subdivision_codes:
          - {geoSubdivisionCode}
      scope: authentication

Auth0 CLI

auth0 network-acl create \
    --description "Example of a complex comparison"
    --active true \
    --priority 1 \
    --rule '{"action":{"block":true},"match":{"geo_country_codes":["{geoCountryCode}"]},"not_match":{"geo_subdivision_codes":["{geoSubdivisionCode}"]},"scope":"authentication"}'

Complex comparisons

You can combine the match and not_match operators in a single Tenant ACL rule to enforce fine-grained access policies.

This Tenant ACL rule example evaluates the geo_country_code and geo_subdivision_code signals to block all traffic from a given country except for a specific state, region, or province within that country.

Management API

To create this Tenant ACL rule with the Management API:

1. Get a Management API access token with the create:network_acls scope.

2. Call the Management API Create access control list endpoint with the following body:

{
  "description": "Example of a complex comparison",
  "active": true,
  "priority": 1,
  "rule": {
    "action": {
      "block": true
    },
    "match": {
      "geo_country_codes": [
        "{geoCountryCode}"
      ]
    },
    "not_match": {
      "geo_subdivision_codes": [
        "{geoSubdivisionCode}"
      ]
    },
    "scope": "authentication"
  }
}

Go SDK

package main

import (
	"context"
	"log"

	"github.com/auth0/go-auth0"
	"github.com/auth0/go-auth0/management"
)

func main() {
	mgmt, err := management.New("{yourDomain}", management.WithClientCredentials("{yourClientId}", "{yourClientSecret}"))
	if err != nil {
		log.Fatal(err)
	}

	networkACL := &management.NetworkACL{
		Description: auth0.String("Example of a complex comparison"),
		Active:      auth0.Bool(true),
		Priority:    auth0.Int(1),
		Rule: &management.NetworkACLRule{
			Action: &management.NetworkACLRuleAction{
				Block: auth0.Bool(true),
			},
			Match: &management.NetworkACLRuleMatch{
				GeoCountryCodes: &[]string{"{geoCountryCode}"},
			},
			NotMatch: &management.NetworkACLRuleMatch{
				GeoSubdivisionCodes: &[]string{"{geoSubdivisionCode}"},
			},
			Scope: auth0.String("authentication"),
		},
	}

	err = mgmt.NetworkACL.Create(context.Background(), networkACL)
	if err != nil {
		log.Fatal(err)
	}
	log.Println("Network ACL has been created")
}

Node SDK

const createNetworkAclPayload: Management.CreateNetworkAclRequestContent = {
  description: "Example of a complex comparison",
  active: true,
  priority: 1,
  rule: {
    action: {
      block: true,
    },
    match: {
      geo_country_codes: ["{geoCountryCode}"],
    },
    not_match: {
      geo_subdivision_codes: ["{geoSubdivisionCode}"],
    },
    scope: "authentication",
  },
};

const createNetworkAcl = await client.networkAcls.create(createNetworkAclPayload);

Terraform

resource "auth0_network_acl" "example_complex_comparison_acl" {
    description = "Example of a complex comparison"
    active = true
    priority = 1
    rule {
        action {
            block = true
        }
        match {
            geo_country_codes = ["{geoCountryCode}"]
        }
        not_match {
            geo_subdivision_codes = ["{geoSubdivisionCode}"]
        }
        scope = "authentication"
    }
}

Deploy CLI

networkACLs:
  - description: Example of a complex comparison
    active: true
    priority: 1
    rule:
      action:
        block: true
      match:
        geo_country_codes:
          - {geoCountryCode}
      not_match:
        geo_subdivision_codes:
          - {geoSubdivisionCode}
      scope: authentication

Auth0 CLI

auth0 network-acl create \
    --description "Example of a complex comparison" \
    --active true \
    --priority 1 \
    --rule '{"action":{"block":true},"match":{"geo_country_codes":["{geoCountryCode}"]},"not_match":{"geo_subdivision_codes":["{geoSubdivisionCode}"]},"scope":"authentication"}'

Enforce traffic through specific infrastructure

You can combine the hostnames and connecting_ipv4_cidrs signals to route requests to your tenant exclusively through your authorized infrastructure, such as a reverse proxy or VPN.

This Tenant ACL rule example blocks access to your canonical and custom domains unless the request originates from a specific set of IP addresses that connect directly to the Auth0 edge. This prevents users from bypassing your security controls by accessing your tenant hostnames directly from the public internet.

Management API

To create this Tenant ACL rule with the Management API:

1. Get a Management API access token with the create:network_acls scope.

2. Call the Management API Create access control list endpoint with the following body:

{
  "description": "Restrict access to specific proxy IPs for custom and canonical domains",
  "active": true,
  "priority": 10,
  "rule": {
    "action": {
      "block": true
    },
    "match": {
      "any": [
        { "hostnames": ["auth.example.com"] },
        { "hostnames": ["my-tenant.us.auth0.com"] }
      ]
    },
    "not_match": {
      "connecting_ipv4_cidrs": [
        "192.0.2.0/24",
        "203.0.113.5/32"
      ]
    },
    "scope": "tenant"
  }
}