Skip to content

resource-specific-documentation.md

Latest commit

 

History

History
1918 lines (1567 loc) · 53.9 KB

resource-specific-documentation.md

File metadata and controls

1918 lines (1567 loc) · 53.9 KB
Raw

Resource-specific Documentation

In general, the Deploy CLI resource configuration files closely match the payload schemas of the Management API.

However, there are some notable nuances to be aware of:

Client Grants

The Deploy CLI's own client grant is intentionally not exported nor configurable by itself. This is done to prevent breaking changes, otherwise the tool could potentially revoke access or otherwise crash in the midst of an import. In a multi-tenant, multi-environment context, it is expect that new tenants will have a designated client already established for the Deploy CLI, as mentioned in the getting started instructions.

Prompts

The prompts resource allows you to configure Universal Login pages, including custom text, custom HTML partials, and screen renderers.

Custom Text: Multilingual text translations follow a hierarchy - language code → prompt ID → screen ID → text ID.

Partials: Custom HTML that can be injected at specific insertion points in prompts.

Screen Renderers: Configure rendering settings for specific prompt-screen combinations. Refer to the Advanced Customizations documentation for more details.

YAML Example

Folder structure when in YAML mode.

./prompts/
    /screenRenderSettings
        /signup-id_signup-id.json
        /login-id_login-id.json
        /login-passwordless_login-passwordless-email-code.json
        /login-passwordless_login-passwordless-sms-otp.json
./tenant.yaml

# Contents of ./tenant.yaml
prompts:
  identifier_first: false
  universal_login_experience: new
  webauthn_platform_first_factor: false
  customText:
    en:
      login:
        login:
          description: Login description in english
          buttonText: Button text
      passkeys:
        passkey-enrollment:
          title: Create a passkey for ${clientName}
          createButtonText: Create a passkey
  partials:
    login:
      login:
        form-content-start: |
          <div class="custom-login-banner">
            <p>Welcome! Please log in to continue.</p>
          </div>
    passkeys:
      passkeys-enrollment:
        form-content-start: |
          <div class="passkey-enrollment-header">
            <p>Enhance your account security by creating a passkey.</p>
          </div>
      passkeys-enrollment-local:
        form-footer-end: |
          <div class="passkey-local-enrollment-info">
            <p>This passkey will be saved to this device only.</p>
          </div>
  screenRenderers:
    - signup-id:
        signup-id: ./prompts/screenRenderSettings/signup-id_signup-id.json
    - login-passwordless:
        login-passwordless-email-code: ./prompts/screenRenderSettings/login-passwordless_login-passwordless-email-code.json
        login-passwordless-sms-otp: ./prompts/screenRenderSettings/login-passwordless_login-passwordless-sms-otp.json

Directory example:

Folder structure when in directory mode.

./prompts/
  ./partials/
    ./login/
      ./login/
        ./form-content-start.liquid
    ./passkeys/
      ./passkeys-enrollment/
        ./form-content-start.liquid
      ./passkeys-enrollment-local/
        ./form-footer-end.liquid
  ./screenRenderSettings/
    ./signup-id_signup-id.json
    ./login-id_login-id.json
    ./login-passwordless_login-passwordless-email-code.json
    ./login-passwordless_login-passwordless-sms-otp.json
    ./login-password_login-password.json
    ./signup-password_signup-password.json
  ./custom-text.json
  ./partials.json
  ./prompts.json

In directory mode, partials.json is a manifest that maps each insertion point to its .liquid file (paths are relative to the prompts/ directory):

Contents of custom-text.json:

{
  "en": {
    "login": {
      "login": {
        "description": "Login description in english",
        "buttonText": "Button text"
      }
    },
    "passkeys": {
      "passkey-enrollment": {
        "title": "Create a passkey for ${clientName}",
        "createButtonText": "Create a passkey"
      }
    }
  }
}

Contents of partials.json:

{
  "login": [
    {
      "login": [
        {
          "name": "form-content-start",
          "template": "partials/login/login/form-content-start.liquid"
        }
      ]
    }
  ],
  "passkeys": [
    {
      "passkeys-enrollment": [
        {
          "name": "form-content-start",
          "template": "partials/passkeys/passkeys-enrollment/form-content-start.liquid"
        }
      ],
      "passkeys-enrollment-local": [
        {
          "name": "form-footer-end",
          "template": "partials/passkeys/passkeys-enrollment-local/form-footer-end.liquid"
        }
      ]
    }
  ]
}

Contents of partials/login/login/form-content-start.liquid:

<div class="login-notice">
  Welcome back! Please log in to continue.
</div>

Contents of partials/passkeys/passkeys-enrollment/form-content-start.liquid:

<div class="passkey-enrollment-header">
  <p>Enhance your account security by creating a passkey.</p>
  <p>Passkeys provide a faster and more secure way to sign in.</p>
</div>

Contents of screenRenderSettings/signup-id_signup-id.json:

{
  "prompt": "signup-id",
  "screen": "signup-id",
  "rendering_mode": "advanced",
  "context_configuration": ["branding.settings", "branding.themes.default"],
  "default_head_tags_disabled": false,
  "head_tags": [
    {
      "tag": "script",
      "attributes": {
        "src": "URL_TO_YOUR_ASSET",
        "async": true,
        "defer": true,
        "integrity": ["ASSET_SHA"]
      }
    }
  ],
  "filters": {
    "match_type": "includes_any",
    "clients": [
      {
        "id": "SeunfRe6p8EXxV6I0g9kMYdT1DxpfC38",
        "metadata": { "key1": "value1" }
      }
    ]
  },
  "use_page_template": false
}

Connections (Google Workspace directory provisioning)

The Deploy CLI supports managing the directory_provisioning_configuration for Google Workspace (google-apps) connections. Only google-apps connections are processed for directory provisioning; other strategies will ignore this block. Deleting directory provisioning requires AUTH0_ALLOW_DELETE=true.

The mapping array pairs Auth0 user fields with IdP fields, and synchronize_automatically controls whether Auth0 runs scheduled sync jobs for the connection.

The synchronize_groups field controls group provisioning.

YAML Example

connections:
  - name: google-workspace
    strategy: google-apps
    options:
      domain: example.com
      tenant_domain: example.com
      client_id: 'some_client_id'
      client_secret: 'some_client_secret'
      api_enable_groups: true
      api_enable_users: true
    directory_provisioning_configuration:
      mapping:
        - auth0: email
          idp: mail
        - auth0: name
          idp: displayName
      synchronize_automatically: false
      synchronize_groups: selected
      synchronized_groups:
        - id: 'group-id-1'
        - id: 'group-id-2'

Directory Example

./connections/google-apps-directory-provisioning.json

{
  "name": "google-apps-directory-provisioning",
  "strategy": "google-apps",
  "enabled_clients": ["My SPA"],
  "options": {
    "domain": "example.com",
    "tenant_domain": "example.com",
    "client_id": "some_client_id",
    "client_secret": "some_client_secret",
    "api_enable_groups": true,
    "api_enable_users": true
  },
  "directory_provisioning_configuration": {
    "mapping": [
      { "auth0": "email", "idp": "mail" },
      { "auth0": "name", "idp": "displayName" }
    ],
    "synchronize_automatically": false,
    "synchronize_groups": "selected",
    "synchronized_groups": [{ "id": "group-id-1" }, { "id": "group-id-2" }]
  }
}

Connections (OIDC and Okta token endpoint authentication options)

For enterprise connections with strategy oidc or okta, the Deploy CLI supports these optional fields under connections[].options:

  • token_endpoint_auth_signing_alg (string): Allowed values are RS256, RS384, RS512, PS256, PS384, ES256, ES384.
  • id_token_signed_response_algs (string[]): Allow-list for incoming ID token signing algorithms. Allowed values are RS256, RS384, RS512, PS256, PS384, ES256, ES384.
  • token_endpoint_jwtca_aud_format (string): Allowed values are issuer or token_endpoint.

YAML Example

connections:
  - name: enterprise-oidc
    strategy: oidc
    enabled_clients:
      - My SPA
    options:
      type: back_channel
      issuer: https://example-idp.com
      jwks_uri: https://example-idp.com/.well-known/jwks.json
      token_endpoint_auth_signing_alg: RS384
      id_token_signed_response_algs:
        - RS256
        - RS384
      token_endpoint_jwtca_aud_format: token_endpoint

Directory Example

./connections/enterprise-oidc.json

{
  "name": "enterprise-oidc",
  "strategy": "oidc",
  "enabled_clients": ["My SPA"],
  "options": {
    "type": "back_channel",
    "issuer": "https://example-idp.com",
    "jwks_uri": "https://example-idp.com/.well-known/jwks.json",
    "token_endpoint_auth_signing_alg": "RS384",
    "id_token_signed_response_algs": ["RS256", "RS384"],
    "token_endpoint_jwtca_aud_format": "token_endpoint"
  }
}

Connections (Cross App Access — Requesting Application)

Early Access: Requires the token_vault_xaa feature flag to be enabled on the tenant.

For enterprise connections with strategy oidc or okta, the Deploy CLI supports configuring the connection as a Requesting Application for Cross App Access via the top-level cross_app_access_requesting_app field:

  • cross_app_access_requesting_app.active (boolean): Set to true to enable the connection as a Requesting Application for Cross App Access. Defaults to true.

YAML Example

connections:
  - name: enterprise-oidc
    strategy: oidc
    cross_app_access_requesting_app:
      active: true
    options:
      type: back_channel
      issuer: https://example-idp.com
      jwks_uri: https://example-idp.com/.well-known/jwks.json

Directory Example

./connections/enterprise-oidc.json

{
  "name": "enterprise-oidc",
  "strategy": "oidc",
  "cross_app_access_requesting_app": {
    "active": true
  },
  "options": {
    "type": "back_channel",
    "issuer": "https://example-idp.com",
    "jwks_uri": "https://example-idp.com/.well-known/jwks.json"
  }
}

Connections (Cross App Access — Resource Application)

Early Access: Part of the XAA (Cross App Access) — Auth0 as Resource Application Authorization Server feature.

The Deploy CLI supports configuring a connection as a Resource Application for Cross App Access via the top-level cross_app_access_resource_app field. This is supported for enterprise connections including SAML (strategy: samlp) and OIDC (strategy: oidc).

  • cross_app_access_resource_app.status ("enabled" | "disabled"): Enables or disables the connection as a Resource Application for Cross App Access.

For SAML connections, the discovery_url and oidc_metadata connection options — previously only supported for OIDC connections — are now also accepted under options.

YAML Example

connections:
  - name: enterprise-saml
    strategy: samlp
    cross_app_access_resource_app:
      status: enabled
    options:
      discovery_url: https://example-idp.com/.well-known/openid-configuration
      oidc_metadata:
        issuer: https://example-idp.com

Directory Example

./connections/enterprise-saml.json

{
  "name": "enterprise-saml",
  "strategy": "samlp",
  "cross_app_access_resource_app": {
    "status": "enabled"
  },
  "options": {
    "discovery_url": "https://example-idp.com/.well-known/openid-configuration",
    "oidc_metadata": {
      "issuer": "https://example-idp.com"
    }
  }
}

Clients (Cross App Access — Identity Assertion Authorization Grant)

Early Access: Part of the XAA (Cross App Access) — Auth0 as Resource Application Authorization Server feature.

The Deploy CLI supports the identity_assertion_authorization_grant property on clients, which enables the client to participate in Cross App Access (ID-JAG) token exchange.

  • identity_assertion_authorization_grant.active (boolean): Set to true to enable ID-JAG exchange for the client.
clients:
  - name: My XAA Client
    identity_assertion_authorization_grant:
      active: true

Databases

When managing database connections, the values of options.customScripts point to specific javascript files relative to the path of the output folder. Otherwise, the payload closely matches that of the Management API.

YAML Example

Folder structure when in YAML mode.

./databases/
    /Username-Password-Authentication
        /change_password.js
        /create.js
        /delete.js
        /get_user.js
        /login.js
        /verify.js
./tenant.yaml

# Contents of ./tenant.yaml
databases:
  - name: Username-Password-Authentication
    # ...
    options:
      # ...
      customScripts:
        change_password: ./databases/Username-Password-Authentication/change_password.js
        create: ./databases/Username-Password-Authentication/create.js
        delete: ./databases/Username-Password-Authentication/delete.js
        get_user: ./databases/Username-Password-Authentication/get_user.js
        login: ./databases/Username-Password-Authentication/login.js
        verify: ./databases/Username-Password-Authentication/verify.js

Directory Example

Folder structure when in directory mode.

./database-connections/
    ./Username-Password-Authentication/
        ./change_password.js
        ./create.js
        ./database.json
        ./delete.js
        ./get_user.js
        ./login.js
        ./verify.js

Contents of database.json

{
  "options": {
    "customScripts": {
      "change_password": "./change_password.js",
      "create": "./create.js",
      "delete": "./delete.js",
      "get_user": "./get_user.js",
      "login": "./login.js",
      "verify": "./verify.js"
    }
  }
}

Resource Servers

Resource servers (APIs) configuration supports the Management API payload schema. The following fields are supported:

YAML Example

resourceServers:
  - name: My API
    identifier: https://api.example.com
    proof_of_possession:
      mechanism: dpop
      required: true
      required_for: public_clients

Directory Example

{
  "name": "My API",
  "identifier": "https://api.example.com",
  "proof_of_possession": {
    "mechanism": "mtls",
    "required": true,
    "required_for": "all_clients"
  }
}

Auth0 My Account API — authorization_policy

The authorization_policy field can be set on the Auth0 My Account API resource server (the system resource server with identifier https://<tenant-domain>/me/) when the acr feature flag is enabled on the tenant. It specifies an Authentication Context Class Reference (ACR) policy that controls the authentication assurance requirements for access tokens issued to that API.

YAML Example

resourceServers:
  - name: Auth0 My Account API
    identifier: https://your-tenant.auth0.com/me/
    authorization_policy:
      policy_id: '019b76da-a800-73c9-b656-b349ae415c17'

To clear the policy, set it to null:

resourceServers:
  - name: Auth0 My Account API
    identifier: https://your-tenant.auth0.com/me/
    authorization_policy: null

Directory Example

{
  "name": "Auth0 My Account API",
  "identifier": "https://your-tenant.auth0.com/me/",
  "authorization_policy": {
    "policy_id": "019b76da-a800-73c9-b656-b349ae415c17"
  }
}

Note: authorization_policy is only accepted by the Auth0 API for the My Account resource server and only when the acr feature flag is enabled on the tenant.

Online Refresh Tokens — allow_online_access and allow_online_access_with_ephemeral_sessions

The allow_online_access field enables issuance of Online Refresh Tokens (ORTs) for a resource server. ORTs are stateless, non-rotating tokens bound to the Auth0 session lifetime — when the session expires or is revoked, the ORT becomes invalid.

allow_online_access_with_ephemeral_sessions permits ORT issuance even when the session uses a non-persistent (ephemeral) cookie. This field can only be set to true if allow_online_access is also true.

Both fields default to false and require the online_refresh_tokens feature flag to be enabled on the tenant.

YAML Example

resourceServers:
  - name: My API
    identifier: https://api.example.com
    allow_online_access: true
    allow_online_access_with_ephemeral_sessions: false

Directory Example

{
  "name": "My API",
  "identifier": "https://api.example.com",
  "allow_online_access": true,
  "allow_online_access_with_ephemeral_sessions": false
}

Universal Login

Pages

When overriding the Universal Login with custom HTML, the error, login, multi-factor authentication and password reset contents are organized in specific HTML pages.

YAML Example

Folder structure when in YAML mode.

./pages/
    /error_page.html
    /guardian_multifactor.html
    /login.html
    /password_reset.html
./tenant.yaml

# Contents of ./tenant.yaml
pages:
  - name: error_page
    html: ./pages/error_page.html
    show_log_link: false
    url: https://mycompany.org/error
  - name: guardian_multifactor
    enabled: true
    html: ./pages/guardian_multifactor.html
  - name: login
    enabled: false
    html: ./pages/login.html
  - name: password_reset
    enabled: true
    html: ./pages/password_reset.html

Directory Example

Folder structure when in directory mode.

./pages/
    ./error_page.html
    ./error_page.json
    ./guardian_multifactor.html
    ./guardian_multifactor.json
    ./login.html
    ./login.json
    ./password_reset.html
    ./password_reset.json

Contents of login.json

{
  "name": "login",
  "enabled": false,
  "html": "./login.html"
}

Contents of error_page.json

{
  "html": "./error_page.html",
  "show_log_link": false,
  "url": "https://mycompany.org/error",
  "name": "error_page"
}

Contents of guardian_multifactor.json

{
  "enabled": true,
  "html": "./guardian_multifactor.html",
  "name": "guardian_multifactor"
}

Contents of password_reset.json

{
  "enabled": true,
  "html": "./password_reset.html",
  "name": "password_reset"
}

emailTemplates

When managing email templates, the values of options.body and options.body point to specific HTML files relative to the path of the output folder. Otherwise, the payload closely matches that of the Management API.

YAML Example

Folder structure when in YAML mode.

./emailTemplates/
    ./verify_email.html
    ./welcome_email.html
    ./password_reset.html
    ./reset_email.html
    ./reset_email_by_code.html
./tenant.yaml

# Contents of ./tenant.yaml
emailTemplates:
  - template: 'verify_email'
    enabled: true
    syntax: 'liquid'
    from: 'test@email.com'
    subject: 'something'
    body: 'emailTemplates/change_email.html'

  - template: 'welcome_email'
    enabled: true
    syntax: 'liquid'
    from: 'test@email.com'
    subject: 'something'
    body: 'emailTemplates/change_email.html'

  - template: 'password_reset'
    enabled: true
    syntax: 'liquid'
    from: 'test@email.com'
    subject: 'something'
    body: 'emailTemplates/change_email.html'

  - template: 'reset_email_by_code'
    enabled: true
    syntax: 'liquid'
    from: 'test@email.com'
    subject: 'something'
    body: 'emailTemplates/change_email.html'

Directory Example

Folder structure when in directory mode.
./emailTemplates/
    ./welcome_email.html
    ./welcome_email.json
    ./reset_email.html
    ./reset_email.json
    ./reset_email_by_code.html
    ./reset_email_by_code.json

Contents of welcome_email.json

{
  "name": "welcome_email",
  "enabled": true,
  "html": "./welcome_email.html"
}

Contents of reset_email.json

{
  "name": "reset_email",
  "enabled": true,
  "html": "./reset_email.html"
}

Contents of reset_email_by_code.json

{
  "name": "reset_email_by_code",
  "enabled": true,
  "html": "./reset_email_by_code.html"
}

Branding

This resource allows to manage branding within your Auth0 tenant. Auth0 can be customized with a look and feel that aligns with your organization's brand requirements and user expectations. universal_login template can be customized (make sure to add read:custom_domains scope to export templates).

YAML Example

Folder structure when in YAML mode.

branding:
  colors:
    page_background: '#FF4F40'
    primary: '#2A2E35'
  favicon_url: https://example.com/favicon.png
  font:
    url: https://example.com/font.woff
  logo_url: https://example.com/logo.png
  templates:
    - template: universal_login
      body: ./branding_templates/universal_login.html

Directory Example

Folder structure when in directory mode.

{
  "colors": {
    "page_background": "#FF4F40",
    "primary": "#2A2E35"
  },
  "favicon_url": "https://example.com/favicon.png",
  "font": {
    "url": "https://example.com/font.woff"
  },
  "logo_url": "https://example.com/logo.png"
}

For universal_login template templates/ will be created.

  • templates/universal_login.html
<!DOCTYPE html>
<html>
  <head>
    {%- auth0:head -%}
  </head>
  <body>
    {%- auth0:widget -%}
    <div>page teamplate</div>
  </body>
</html>
  • templates/universal_login.json
{
  "template": "universal_login",
  "body": "./universal_login.html"
}

Themes (Identifier display settings)

Early Access: Requires the universal_login_theme_identifiers feature flag to be enabled on the tenant. When the flag is off, the Auth0 API rejects a theme write that includes identifiers and strips the field from responses.

The Deploy CLI supports configuring identifier display settings on the branding theme via the top-level identifiers object. All three members are required when identifiers is supplied:

  • identifiers.login_display (string): Login display mode. One of separate, unified.
  • identifiers.otp_autocomplete (boolean): Whether OTP autocomplete is enabled.
  • identifiers.phone_display (object): Phone number display settings.
    • identifiers.phone_display.formatting (string): One of international, regional.
    • identifiers.phone_display.masking (string): One of hide_country_code, mask_digits, show_all.

YAML Example

themes:
  - displayName: Default theme
    borders: { ... }
    colors: { ... }
    fonts: { ... }
    page_background: { ... }
    widget: { ... }
    identifiers:
      login_display: unified
      otp_autocomplete: true
      phone_display:
        masking: mask_digits
        formatting: international

Directory Example

./themes/Default theme.json

{
  "displayName": "Default theme",
  "borders": { "...": "..." },
  "colors": { "...": "..." },
  "fonts": { "...": "..." },
  "page_background": { "...": "..." },
  "widget": { "...": "..." },
  "identifiers": {
    "login_display": "unified",
    "otp_autocomplete": true,
    "phone_display": {
      "masking": "mask_digits",
      "formatting": "international"
    }
  }
}

Tenant Settings (Country codes)

Early Access: Requires the tenant_country_codes_filtering feature flag to be enabled on the tenant. When the flag is off, the Auth0 API rejects a tenant settings write that includes country_codes.

The Deploy CLI supports configuring phone country code filtering for identifier input via the top-level country_codes object in tenant settings:

  • country_codes.list (array of string): ISO 3166-1 alpha-2 codes (e.g. US, GB). Must be non-empty and unique.
  • country_codes.mode (string): Whether the list is an allowlist or denylist. One of allow, deny.

Set country_codes: null to remove filtering (allow all countries).

YAML Example

tenant:
  country_codes:
    list:
      - US
      - GB
      - CA
    mode: allow

Directory Example

./tenant.json

{
  "country_codes": {
    "list": ["US", "GB", "CA"],
    "mode": "allow"
  }
}

Custom Domains

Custom domains allow you to use your own domain for authentication instead of the default Auth0 domain. The Deploy CLI supports managing custom domains in both directory and YAML modes.

Custom domains have the following key properties:

  • domain: The custom domain name (required)
  • type: Certificate management type - either auth0_managed_certs or self_managed_certs (required)
  • custom_client_ip_header: Header to use for client IP detection (optional, one of: true-client-ip, cf-connecting-ip, x-forwarded-for, or null)
  • tls_policy: TLS policy to use (defaults to recommended)
  • verification_method: Domain verification method (defaults to txt)
  • domain_metadata: Metadata associated with the custom domain (optional, max 10 properties)
  • relying_party_identifier: Relying Party ID (rpId) to be used for Passkeys on this custom domain. If not provided or set to null, the full domain will be used. (optional)

Note: The relying_party_identifier should be a suffix of the domain name. For example, if your domain is auth.example.com, the relying_party_identifier could be example.com.

YAML Example

# Contents of ./tenant.yaml
customDomains:
  - domain: 'auth.example.com'
    type: 'auth0_managed_certs'
    tls_policy: 'recommended'
    custom_client_ip_header: 'cf-connecting-ip'
    domain_metadata:
      environment: 'production'
      team: 'platform'
    relying_party_identifier: 'example.com'
  - domain: 'login.myapp.com'
    type: 'self_managed_certs'
    verification_method: 'txt'

Directory Example

Folder structure when in directory mode.

./customDomains/
    ./auth.example.com.json
    ./login.myapp.com.json

Contents of auth.example.com.json:

{
  "domain": "auth.example.com",
  "type": "auth0_managed_certs",
  "tls_policy": "recommended",
  "custom_client_ip_header": "cf-connecting-ip",
  "domain_metadata": {
    "environment": "production",
    "team": "platform"
  },
  "relying_party_identifier": "example.com"
}

Contents of login.myapp.com.json:

{
  "domain": "login.myapp.com",
  "type": "self_managed_certs",
  "verification_method": "txt"
}

For more details, see the Management API documentation.

NetworkACL

Tenant Network Access Control Lists (NetworkACLs) allow you to configure rules that control access to your Auth0 tenant based on IP addresses, geographical locations, and other network criteria. The Deploy CLI supports managing NetworkACLs in both directory and YAML modes.Refer more on this.

NetworkACLs have the following key properties:

  • description: A descriptive name for the rule
  • active: Boolean indicating if the rule is active
  • priority: Number (minimum 1) determining the order of rule evaluation (lower numbers have higher priority)
  • rule: The rule configuration containing:
    • action: The action to take (block, allow, log, or redirect)
    • scope: The scope of the rule ('management', 'authentication', or 'tenant')
    • match or not_match: Criteria for matching requests

The match and not_match criteria also support an auth0_managed array for matching Auth0-managed IP ranges (e.g. auth0.icloud_relay_proxy, auth0.low_reputation). Each value must follow the pattern ^auth0\.[^.\s]+$. This is an Early Access feature gated behind the tenant_acl_curated_blocklists feature flag and requires the advanced-breached-password-detection entitlement; the API rejects rules using auth0_managed with an HTTP 403 if the tenant is not entitled.

YAML Example

# Contents of ./tenant.yaml
networkACLs:
  - description: 'Allow Specific Countries'
    active: true
    priority: 2
    rule:
      action:
        allow: true
      scope: 'authentication'
      match:
        geo_country_codes: ['US', 'CA']
  - description: 'Redirect Specific User Agents'
    active: true
    priority: 3
    rule:
      action:
        block: true
      scope: 'management'
      not_match:
        user_agents: ['BadBot/1.0']
  - description: 'Block iCloud Private Relay Exits'
    active: true
    priority: 4
    rule:
      action:
        block: true
      scope: 'tenant'
      match:
        auth0_managed: ['auth0.icloud_relay_proxy']

Directory Example

Folder structure when in directory mode.

./networkACLs/
    ./Allow Specific Countries-p-2.json
    ./Redirect Specific User Agents-p-3.json
    ./Block iCloud Private Relay Exits-p-4.json

Contents of Allow Specific Countries-p-2.json:

{
  "description": "Allow Specific Countries",
  "active": true,
  "priority": 2,
  "rule": {
    "action": {
      "allow": true
    },
    "scope": "authentication",
    "match": {
      "geo_country_codes": ["US", "CA"]
    }
  }
}

Contents of Redirect Specific User Agents-p-3.json:

{
  "description": "Redirect Specific User Agents",
  "active": true,
  "priority": 3,
  "rule": {
    "action": {
      "block": true
    },
    "scope": "management",
    "match": {
      "user_agents": ["BadBot/1.0"]
    }
  }
}

Contents of Block iCloud Private Relay Exits-p-4.json:

{
  "description": "Block iCloud Private Relay Exits",
  "active": true,
  "priority": 4,
  "rule": {
    "action": {
      "block": true
    },
    "scope": "tenant",
    "match": {
      "auth0_managed": ["auth0.icloud_relay_proxy"]
    }
  }
}

PhoneProviders

When managing phone providers, credentials are never exported.

For the Twilio phoneProvider, we add the placeholder ##TWILIO_AUTH_TOKEN## for the credential's auth_token, which can be used with keyword replacement.

Refer to keyword-replacement.md, multi-environment-workflow.md, and the Management API for more details.

YAML Example

# Contents of ./tenant.yaml
phoneProviders:
  - name: twilio
    configuration:
      sid: 'twilio_sid'
      default_from: '+1234567890'
      delivery_methods:
        - text
        - voice
    disabled: false
    credentials:
      auth_token: '##TWILIO_AUTH_TOKEN##'

Directory Example

[
  {
    "name": "twilio",
    "disabled": true,
    "configuration": {
      "sid": "twilio_sid",
      "default_from": "+1234567890",
      "delivery_methods": ["text", "voice"]
    },
    "credentials": {
      "auth_token": "##TWILIO_AUTH_TOKEN##"
    }
  }
]

PhoneTemplates

Phone templates allow you to customize the SMS and voice messages sent to users for phone-based authentication. Refer to the Management API for more details.

YAML Example

# Contents of ./tenant.yaml
phoneTemplates:
  - type: otp_verify
    disabled: false
    content:
      from: '+12341234567'
      body:
        text: 'Your verification code is {{ code }}'
        voice: 'Your verification code is {{ code }}'
  - type: otp_enroll
    disabled: false
    content:
      from: '+12341234567'
      body:
        text: 'Your enrollment code is {{ code }}'

Directory Example

Create individual JSON files for each template in the phone-templates directory:

phone-templates/
├── otp_verify.json
├── otp_enroll.json
├── change_password.json
└── ...

Example phone-templates/otp_verify.json:

{
  "type": "otp_verify",
  "disabled": false,
  "content": {
    "from": "+12341234567",
    "body": {
      "text": "Your verification code is {{ code }}",
      "voice": "Your verification code is {{ code }}"
    }
  }
}

Connection Profiles

Application specific configuration for use with the OIN Express Configuration feature

YAML Example

# Contents of ./tenant.yaml
connectionProfiles:
  - name: 'Enterprise SSO Profile'
    organization:
      show_as_button: 'required'
      assign_membership_on_login: 'required'
    connection_name_prefix_template: 'org-{organization_name}'
    enabled_features:
      - scim
      - universal_logout
    strategy_overrides:
      samlp:
        enabled_features:
          - universal_logout
      oidc:
        enabled_features:
          - scim
          - universal_logout
  - name: 'Basic Connection Profile'
    organization:
      show_as_button: 'optional'
      assign_membership_on_login: 'optional'
    enabled_features:
      - scim

Directory Example

File: ./connection-profiles/Enterprise SSO Profile.json

{
  "name": "Enterprise SSO Profile",
  "organization": {
    "show_as_button": "required",
    "assign_membership_on_login": "required"
  },
  "connection_name_prefix_template": "org-{organization_name}",
  "enabled_features": ["scim", "universal_logout"],
  "strategy_overrides": {
    "samlp": {
      "enabled_features": ["universal_logout"]
    },
    "oidc": {
      "enabled_features": ["scim", "universal_logout"]
    }
  }
}

Express Configuration on Clients

Connection profiles are used in conjunction with the express_configuration property on client applications: (In order to use express_configuration app_type should not be 'express_configuration')

clients:
  - name: 'My Enterprise App'
    app_type: 'regular_web'
    express_configuration:
      initiate_login_uri_template: 'https://myapp.com/sso/start?org={organization_name}&conn={connection_name}'
      user_attribute_profile_id: 'My User Attribute Profile'
      connection_profile_id: 'Enterprise SSO Profile' # Reference to connection profile
      enable_client: true
      enable_organization: true
      okta_oin_client_id: 'My Okta OIN Client'
      admin_login_domain: 'login.myapp.com'
      linked_clients:
        - client_id: 'client_id_of_mobile_app'

For more details, see the Management API documentation.

Self-Service Profiles

Self-Service Profiles enable organizations to configure self-service SSO flows for their users. These profiles define the user attributes to collect, branding customization, and which identity provider strategies are allowed during the self-service setup process.

Note: You cannot specify both user_attribute_profile_id and user_attributes in the same profile. Use user_attribute_profile_id to reference an existing User Attribute Profile, or define user_attributes inline.

YAML Example

# Contents of ./tenant.yaml
selfServiceProfiles:
  - name: 'Enterprise SSO Profile'
    description: 'Self-service SSO for enterprise customers'
    allowed_strategies:
      - oidc
      - samlp
      - okta
    user_attributes:
      - name: email
        description: Email of the User
        is_optional: false
      - name: name
        description: Name of the User
        is_optional: true
    branding:
      logo_url: 'https://example.com/logo.png'
      colors:
        primary: '#19aecc'
    customText:
      en:
        get-started:
          introduction: 'Welcome! With <p>only a few steps</p> you will be able to setup your new connection.'

  - name: 'Simple SSO Profile'
    description: 'Basic SSO profile'
    user_attribute_profile_id: 'My User Attribute Profile'
    allowed_strategies:
      - google-apps
      - adfs

Directory Example

Folder structure when in directory mode.

./self-service-profiles/
    ./Enterprise SSO Profile.json
    ./Simple SSO Profile.json

Contents of Enterprise SSO Profile.json:

{
  "name": "Enterprise SSO Profile",
  "description": "Self-service SSO for enterprise customers",
  "allowed_strategies": ["oidc", "samlp", "okta"],
  "user_attributes": [
    {
      "name": "email",
      "description": "Email of the User",
      "is_optional": false
    },
    {
      "name": "name",
      "description": "Name of the User",
      "is_optional": true
    }
  ],
  "branding": {
    "logo_url": "https://example.com/logo.png",
    "colors": {
      "primary": "#19aecc"
    }
  },
  "customText": {
    "en": {
      "get-started": {
        "introduction": "Welcome! With <p>only a few steps</p> you will be able to setup your new connection."
      }
    }
  }
}

Contents of Simple SSO Profile.json:

{
  "name": "Simple SSO Profile",
  "description": "Basic SSO profile",
  "user_attribute_profile_id": "My User Attribute Profile",
  "allowed_strategies": ["google-apps", "adfs"]
}

For more details, see the Management API documentation.

Risk Assessments

Risk assessments configuration allows you to enable or disable risk assessment features for your tenant.

  • settings.enabled: toggles the feature true/flase (required)
  • new_device.remember_for (optional): days to remember devices

YAML Example

# Contents of ./tenant.yaml
riskAssessment:
  settings:
    enabled: true
  new_device:
    remember_for: 30

Directory Example

Folder: ./risk-assessment/

File: ./risk-assessment/settings.json

{
  "settings": {
    "enabled": true
  },
  "new_device": {
    "remember_for": 30
  }
}

For more details, see the Management API documentation.

Action Modules

Action modules are reusable code modules that can be shared across multiple Auth0 actions. They allow you to create common utility functions, helpers, and libraries that can be imported and used by any action in your tenant.

YAML Example

# Contents of ./tenant.yaml
actionModules:
  - name: auth-helper
    code: ./action-modules/auth-helper/code.js
    dependencies:
      - name: axios
        version: 1.6.0
      - name: jsonwebtoken
        version: 9.0.0
    secrets:
      - name: JWT_SECRET
        value: ##JWT_SECRET##

  - name: notification-helper
    code: ./action-modules/notification-helper/code.js
    dependencies:
      - name: uuid
        version: 9.0.0
    secrets: []

Folder structure when in YAML mode:

./action-modules/
    /auth-helper/
        /code.js
    /notification-helper/
        /code.js
./tenant.yaml

Directory Example

Folder structure when in directory mode:

./action-modules/
    ./auth-helper.json
    ./auth-helper/
        ./code.js
    ./notification-helper.json
    ./notification-helper/
        ./code.js

Contents of auth-helper.json:

{
  "name": "auth-helper",
  "code": "./action-modules/auth-helper/code.js",
  "dependencies": [
    {
      "name": "axios",
      "version": "1.6.0"
    },
    {
      "name": "jsonwebtoken",
      "version": "9.0.0"
    }
  ],
  "secrets": [
    {
      "name": "JWT_SECRET",
      "value": "##JWT_SECRET##"
    }
  ]
}

Contents of auth-helper/code.js:

const jwt = require('jsonwebtoken');
const axios = require('axios');

/**
 * Auth Helper Module
 * Provides JWT validation and token refresh utilities
 */
module.exports = {
  async validateToken(token) {
    const secret = actions.secrets.JWT_SECRET;
    try {
      return jwt.verify(token, secret);
    } catch (error) {
      throw new Error('Invalid token: ' + error.message);
    }
  },

  async fetchUserData(userId) {
    const response = await axios.get(`https://api.example.com/users/${userId}`);
    return response.data;
  },
};

Using Action Modules in Actions

Actions can reference action modules in their configuration:

YAML Example:

actions:
  - name: send-phone-message
    code: ./actions/send-phone-message/code.js
    supported_triggers:
      - id: send-phone-message
        version: v1
    modules:
      - module_name: notification-helper
        module_version_number: 1

Directory Example:

Contents of actions/send-phone-message.json:

{
  "name": "send-phone-message",
  "code": "./actions/send-phone-message/code.js",
  "supported_triggers": [
    {
      "id": "send-phone-message",
      "version": "v1"
    }
  ],
  "modules": [
    {
      "module_name": "notification-helper",
      "module_version_number": 1
    }
  ]
}

The action can then import and use the module in its code:

const notificationHelper = require('actions:notification-helper');

exports.onExecuteSendPhoneMessage = async (event) => {
  const message = notificationHelper.formatMessage(
    event.user.phone_number,
    'Your verification code'
  );
};

Supplemental Signals

Supplemental signals configuration allows you to enable third-party integrations for enhanced security and risk assessment.

  • akamai_enabled (boolean): Enable processing of incoming Akamai headers for supplemental security signals

YAML Example

# Contents of ./tenant.yaml
supplementalSignals:
  akamai_enabled: true

Directory Example

Folder: ./supplemental-signals.json

{
  "akamai_enabled": true
}

For more details, see the Management API documentation.

Event Streams

Event Streams allow you to subscribe to Auth0 tenant events and forward them to external destinations (webhook, AWS EventBridge, or an Auth0 Action).

Schema Properties

  • name (string, required): Display name for the event stream.
  • status (string): enabled or disabled.
  • subscriptions (array): List of event types to subscribe to. Each entry has an event_type string (e.g. user.created, organization.member.added). If omitted, no events are forwarded.
  • destination (object, required): Destination configuration.
    • type (string): webhook, eventbridge, or action.
    • configuration (object): Destination-specific settings.

Webhook destination

{
  "type": "webhook",
  "configuration": {
    "webhook_endpoint": "https://example.com/events",
    "webhook_authorization": {
      "method": "bearer"
    }
  }
}

Supported webhook_authorization methods: basic (username only returned), bearer, custom_header. Secrets are masked on export unless AUTH0_EXPORT_SECRETS: true.

AWS EventBridge destination

{
  "type": "eventbridge",
  "configuration": {
    "aws_account_id": "123456789012",
    "aws_region": "us-east-1"
  }
}

Note: EventBridge streams cannot have their destination updated after creation. Only name, subscriptions, and status can be patched.

Action destination

{
  "type": "action",
  "configuration": {
    "action_id": "act_abc123"
  }
}

Note: like EventBridge, Action streams cannot have their destination updated after creation. Only name, subscriptions, and status can be patched — the destination is stripped from update payloads (an info message is logged when this happens).

YAML Example

# Contents of ./tenant.yaml
eventStreams:
  - name: My Webhook Stream
    status: enabled
    subscriptions:
      - event_type: user.created
      - event_type: user.deleted
    destination:
      type: webhook
      configuration:
        webhook_endpoint: https://example.com/events
        webhook_authorization:
          method: bearer

Directory Example

Folder: ./event-streams/

Each event stream is stored as a separate JSON file named after the stream (e.g. my-webhook-stream.json):

{
  "name": "My Webhook Stream",
  "status": "enabled",
  "subscriptions": [{ "event_type": "user.created" }],
  "destination": {
    "type": "webhook",
    "configuration": {
      "webhook_endpoint": "https://example.com/events",
      "webhook_authorization": {
        "method": "bearer"
      }
    }
  }
}

For more details, see the Management API documentation.

Rate Limit Policies

Rate Limit Policies allow you to control the rate at which clients can make authentication requests to the OAuth authentication API. Each policy targets a specific consumer selector (e.g. a specific client, all third-party clients, or a default fallback) and defines the action to take when the limit is exceeded.

Schema Properties

Property Type Required Description
resource string Yes The API protected by the policy. Currently only oauth_authentication_api is supported.
consumer string Yes The consumer type. Currently only client is supported.
consumer_selector string Yes Identifies the target within the consumer. Supported values: client_id:<client_id> to target a specific client, cimd_clients for all CIMD clients, third_party_clients for all third-party clients, or default as a fallback for any unmatched consumer.
configuration.action string Yes The action to take when the rate limit is exceeded. One of: allow, block, log, redirect.
configuration.limit number Required for block, log, redirect Maximum number of requests allowed in a refresh window.
configuration.redirect_uri string Required for redirect The HTTPS URI to redirect to when the rate limit is exceeded.

YAML Example

# Contents of ./tenant.yaml
rateLimitPolicies:
  - resource: oauth_authentication_api
    consumer: client
    consumer_selector: default
    configuration:
      action: block
      limit: 100

  - resource: oauth_authentication_api
    consumer: client
    consumer_selector: third_party_clients
    configuration:
      action: log
      limit: 50

  - resource: oauth_authentication_api
    consumer: client
    consumer_selector: client_id:some-client-id
    configuration:
      action: redirect
      limit: 10
      redirect_uri: https://example.com/rate-limited

Directory Example

Folder: ./rate-limit-policies/

Each rate limit policy is stored as a separate JSON file named after its consumer_selector (e.g. default.json):

{
  "resource": "oauth_authentication_api",
  "consumer": "client",
  "consumer_selector": "default",
  "configuration": {
    "action": "block",
    "limit": 100
  }
}

For more details, see the Management API documentation.

Client Credentials (Private Key JWT / mTLS)

The Deploy CLI supports managing client authentication credentials for Private Key JWT and mTLS. Credentials are child resources of clients, managed via the /clients/{id}/credentials API.

How it works

Export: client_authentication_methods is exported with credential stubs containing only name and credential_type. The pem field is never exported — Auth0 does not return it after creation. If no named credentials exist for a client, client_authentication_methods is omitted entirely from the export.

Deploy: Credential reconciliation only activates when at least one credential in the config contains a pem field. This means a plain export→deploy will never delete existing credentials — pem is the explicit opt-in signal.

  • Creates credentials present in config but missing in Auth0
  • Deletes credentials removed from config (requires AUTH0_ALLOW_DELETE=true)
  • Creates always run before deletes — Auth0 allows max 2 credentials per client, so both exist simultaneously during the rotation window
  • Re-wires client_authentication_methods with resolved credential IDs after reconciliation
  • If client_authentication_methods is absent from the client config entirely, it is treated as intentional deletion — all existing credentials are removed (requires AUTH0_ALLOW_DELETE=true)

Supported credential types

credential_type Auth method key Use case
public_key private_key_jwt Private Key JWT
x509_cert self_signed_tls_client_auth mTLS (self-signed cert)
cert_subject_dn tls_client_auth mTLS (CA-signed cert, subject DN)

Workflow

To add or rotate a credential:

  1. Generate a key pair:

    openssl genrsa -out private.key 2048
openssl rsa -in private.key -pubout -out public.pem

  2. Add the credential to your client config with the public key pem:

    clients:
  - name: My API Client
    client_authentication_methods:
      private_key_jwt:
        credentials:
          - name: my-key-v2
            credential_type: public_key
            pem: |
              -----BEGIN PUBLIC KEY-----
              MIIBIjANBgkq...
              -----END PUBLIC KEY-----

  3. Deploy — the credential is created in Auth0 and client_authentication_methods is updated.

  4. To rotate: add the new key alongside the old one (both exist simultaneously), then remove the old one in a subsequent deploy.

Export shape (name and credential_type only)

clients:
  - name: My API Client
    client_authentication_methods:
      private_key_jwt:
        credentials:
          - name: my-key-v2
            credential_type: public_key

If no credentials exist for the client, client_authentication_methods is omitted entirely — not exported as an empty object.

Directory Example

./clients/
    ./My API Client.json

Contents of My API Client.json (deploy-time, with pem):

{
  "name": "My API Client",
  "client_authentication_methods": {
    "private_key_jwt": {
      "credentials": [
        {
          "name": "my-key-v2",
          "credential_type": "public_key",
          "pem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"
        }
      ]
    }
  }
}

Note: The pem field must be supplied manually from your key generation step. Never commit private keys — only the public key PEM goes in the config.

Token Vault Privileged Access

Early Access: token_vault_privileged_access requires the token_vault_subject_type_jwt_ea_rollout feature flag to be enabled on the tenant, and writes additionally require the create:client_token_vault_privileged_access / update:client_token_vault_privileged_access scopes. This field is export-only in the Deploy CLI (see below), so these requirements affect only manual configuration on the tenant, not the CLI.

The Deploy CLI exports the token_vault_privileged_access property on clients, which hardens a privileged Token Vault worker by restricting the caller IPs, connections, and scopes it may use at runtime.

Export-only field: token_vault_privileged_access is exported for visibility but is not deployed by the Deploy CLI — it is stripped from create/update payloads. The Management API requires a credentials array (tenant-specific credential id references) whenever the object is sent, and those ids are never persisted by the CLI because they are not portable across tenants. Sending the object without them fails validation, and sending exported ids would re-send stale references on a cross-tenant deploy. Manage token_vault_privileged_access directly on the tenant.

Field Type Description
ip_allowlist array of strings IPv4/IPv6 addresses or CIDR ranges permitted to call token exchange on behalf of this client.
grants array of objects Connection/scope pin objects. Each has a connection (name) and scopes (array). Max 5 connections; max 20 scopes total.

Exported shape (credentials is stripped; ip_allowlist and grants are kept for visibility):

clients:
  - name: My Token Vault Privileged App
    app_type: non_interactive
    token_vault_privileged_access:
      ip_allowlist:
        - '192.168.1.0/24'
        - '10.0.0.1'
      grants:
        - connection: google-oauth2
          scopes:
            - 'https://www.googleapis.com/auth/calendar.readonly'
        - connection: slack
          scopes:
            - 'chat:write'
            - 'channels:read'