Extensibility as custom phone provider deploy cli support

docs/configuring-the-deploy-cli.md

@@ -88,7 +88,7 @@ Boolean. When enabled, will allow the tool to delete resources. Default: `false`
 
 ### `AUTH0_EXCLUDED`
 
-Array of strings. Excludes entire resource types from being managed, bi-directionally. See also: [excluding resources from management](excluding-from-management.md). Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`, `selfServiceProfiles`.
+Array of strings. Excludes entire resource types from being managed, bi-directionally. See also: [excluding resources from management](excluding-from-management.md). Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `phoneProviders`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`, `selfServiceProfiles`.
 
 Cannot be used simultaneously with `AUTH0_INCLUDED_ONLY`.
 
@@ -102,7 +102,7 @@ Cannot be used simultaneously with `AUTH0_INCLUDED_ONLY`.
 
 ### `AUTH0_INCLUDED_ONLY`
 
-Array of strings. Dictates which resource types to _only_ manage, bi-directionally. See also: [excluding resources from management](excluding-from-management.md). Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`, `selfServiceProfiles`.
+Array of strings. Dictates which resource types to _only_ manage, bi-directionally. See also: [excluding resources from management](excluding-from-management.md). Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `phoneProviders`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`, `selfServiceProfiles`.
 
 #### Example
 

docs/resource-specific-documentation.md

@@ -434,3 +434,50 @@ For `universal_login` template `templates/` will be created.
   "body": "./universal_login.html"
 }
 ```
+
+## 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](keyword-replacement.md), [multi-environment-workflow.md](multi-environment-workflow.md), and the [Management API](https://auth0.com/docs/api/management/v2/branding/create-phone-provider) for more details.
+
+
+**YAML Example**
+
+```yaml
+# 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**
+
+```json
+[
+  {
+    "name": "twilio",
+    "disabled": true,
+    "configuration": {
+      "sid": "twilio_sid",
+      "default_from": "+1234567890",
+      "delivery_methods": [
+        "text", "voice"
+      ]
+    },
+    "credentials": {
+      "auth_token": "##TWILIO_AUTH_TOKEN##"
+    }
+  }
+]
+```

examples/directory/phoneProviders/provider.json

@@ -0,0 +1,16 @@
+[
+  {
+    "name": "twilio",
+    "disabled": true,
+    "configuration": {
+      "sid": "twilio_sid",
+      "default_from": "+1234567890",
+      "delivery_methods": [
+        "text", "voice"
+      ]
+    },
+    "credentials": {
+      "auth_token": "some_auth_token"
+    }
+  }
+]

examples/yaml/tenant.yaml

@@ -83,6 +83,17 @@ resourceServers:
         description: "read account"
     # Add other resource server settings (https://auth0.com/docs/api/management/v2#!/Resource_Servers/post_resource_servers)
 
+phoneProviders:
+  - name: twilio
+    configuration:
+      sid: "twilio_sid"
+      default_from: "+1234567890"
+      delivery_methods:
+        - text
+        - voice
+    disabled: false
+    credentials:
+      auth_token: "some_auth_token"
 
 emailProvider:
   name: "smtp"

package.json

@@ -33,7 +33,7 @@
   "homepage": "https://github.com/auth0/auth0-deploy-cli#readme",
   "dependencies": {
     "ajv": "^6.12.6",
-    "auth0": "^4.18.0",
+    "auth0": "^4.19.0",
     "dot-prop": "^5.2.0",
     "fs-extra": "^10.1.0",
     "js-yaml": "^4.1.0",

src/context/defaults.ts

@@ -52,3 +52,26 @@ export function emailProviderDefaults(emailProvider) {
 
   return updated;
 }
+
+export function phoneProviderDefaults(phoneProvider) {
+  const updated = { ...phoneProvider };
+
+  const removeKeysFromOutput = ['id', 'created_at', 'updated_at', 'channel', 'tenant', 'credentials'];
+  removeKeysFromOutput.forEach((key) => {
+    if (key in updated) {
+      delete updated[key];
+    }
+  });
+
+  const apiKeyProviders = ['twilio'];
+
+  // Add placeholder for credentials as they cannot be exported
+  const { name } = updated;
+
+  if (apiKeyProviders.includes(name)) {
+    updated.credentials = {
+      auth_token: `##${name.toUpperCase()}_AUTH_TOKEN##`,
+    };
+  }
+  return updated;
+}

src/context/directory/handlers/index.ts

@@ -19,6 +19,7 @@ import organizations from './organizations';
 import triggers from './triggers';
 import attackProtection from './attackProtection';
 import branding from './branding';
+import phoneProviders from './phoneProvider';
 import logStreams from './logStreams';
 import prompts from './prompts';
 import customDomains from './customDomains';
@@ -66,6 +67,7 @@ const directoryHandlers: {
   triggers,
   attackProtection,
   branding,
+  phoneProviders,
   logStreams,
   prompts,
   customDomains,

src/context/directory/handlers/phoneProvider.ts

@@ -0,0 +1,57 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { constants } from '../../../tools';
+
+import { existsMustBeDir, isFile, dumpJSON, loadJSON } from '../../../utils';
+import { DirectoryHandler } from '.';
+import DirectoryContext from '..';
+import { ParsedAsset } from '../../../types';
+import { PhoneProvider } from '../../../tools/auth0/handlers/phoneProvider';
+import { phoneProviderDefaults } from '../../defaults';
+
+type ParsedPhoneProvider = ParsedAsset<'phoneProviders', PhoneProvider[]>;
+
+function parse(context: DirectoryContext): ParsedPhoneProvider {
+  const phoneProvidersFolder = path.join(context.filePath, constants.PHONE_PROVIDER_DIRECTORY);
+  if (!existsMustBeDir(phoneProvidersFolder)) return { phoneProviders: null }; // Skip
+
+  const providerFile = path.join(phoneProvidersFolder, 'provider.json');
+
+  if (isFile(providerFile)) {
+    return {
+      phoneProviders: loadJSON(providerFile, {
+        mappings: context.mappings,
+        disableKeywordReplacement: context.disableKeywordReplacement,
+      }),
+    };
+  }
+
+  return { phoneProviders: null };
+}
+
+async function dump(context: DirectoryContext): Promise<void> {
+  let { phoneProviders } = context.assets;
+
+  if (!phoneProviders) {
+    return;
+  }// Skip, nothing to dump
+
+  const phoneProvidersFolder = path.join(context.filePath, constants.PHONE_PROVIDER_DIRECTORY);
+  fs.ensureDirSync(phoneProvidersFolder);
+
+  const phoneProviderFile = path.join(phoneProvidersFolder, 'provider.json');
+
+  phoneProviders = phoneProviders.map((provider) => {
+    provider = phoneProviderDefaults(provider);
+    return provider;
+  });
+
+  dumpJSON(phoneProviderFile, phoneProviders);
+}
+
+const phoneProvidersHandler: DirectoryHandler<ParsedPhoneProvider> = {
+  parse,
+  dump,
+};
+
+export default phoneProvidersHandler;

src/context/yaml/handlers/index.ts

@@ -19,6 +19,7 @@ import actions from './actions';
 import triggers from './triggers';
 import attackProtection from './attackProtection';
 import branding from './branding';
+import phoneProviders from './phoneProvider';
 import logStreams from './logStreams';
 import prompts from './prompts';
 import customDomains from './customDomains';
@@ -64,6 +65,7 @@ const yamlHandlers: { [key in AssetTypes]: YAMLHandler<{ [key: string]: unknown
   triggers,
   attackProtection,
   branding,
+  phoneProviders,
   logStreams,
   prompts,
   customDomains,

src/context/yaml/handlers/phoneProvider.ts

@@ -0,0 +1,39 @@
+import { YAMLHandler } from '.';
+import YAMLContext from '..';
+import { PhoneProvider } from '../../../tools/auth0/handlers/phoneProvider';
+import { ParsedAsset } from '../../../types';
+import { phoneProviderDefaults } from '../../defaults';
+
+type ParsedPhoneProviders = ParsedAsset<'phoneProviders', PhoneProvider[] >;
+
+async function parse(context: YAMLContext): Promise<ParsedPhoneProviders> {
+  const { phoneProviders } = context.assets;
+
+  if (!phoneProviders) return { phoneProviders: null };
+
+  return {
+    phoneProviders,
+  };
+}
+
+async function dump(context: YAMLContext): Promise<ParsedPhoneProviders> {
+  if (!context.assets.phoneProviders) return { phoneProviders: null };
+
+  let { phoneProviders } = context.assets;
+
+  phoneProviders = phoneProviders.map((provider) => {
+    provider = phoneProviderDefaults(provider);
+    return provider;
+  });
+
+  return {
+    phoneProviders
+  };
+}
+
+const phoneProviderHandler: YAMLHandler<ParsedPhoneProviders> = {
+  parse,
+  dump,
+};
+
+export default phoneProviderHandler;

src/tools/auth0/handlers/emailProvider.ts

@@ -2,7 +2,6 @@ import { EmailProviderCreate } from 'auth0';
 import { isEmpty } from 'lodash';
 import DefaultHandler, { order } from './default';
 import { Asset, Assets } from '../../../types';
-import log from '../../../logger';
 
 export const schema = { type: 'object' };
 
@@ -46,7 +45,6 @@ export default class EmailProviderHandler extends DefaultHandler {
     if (Object.keys(emailProvider).length === 0) {
       if (this.config('AUTH0_ALLOW_DELETE') === true) {
         // await this.client.emails.delete(); is not supported
-        existing.enabled = false;
         if (isEmpty(existing.credentials)) {
           delete existing.credentials;
         }
@@ -57,14 +55,6 @@ export default class EmailProviderHandler extends DefaultHandler {
       return;
     }
 
-    if (existing.name) {
-      if (existing.name !== emailProvider.name) {
-        // Delete the current provider as it's different
-        // await this.client.emailProvider.delete(); is not supported
-        existing.enabled = false;
-      }
-    }
-
     if (existing.name) {
       const updated = await this.client.emails.update(emailProvider);
       this.updated += 1;

src/tools/auth0/handlers/index.ts

@@ -18,6 +18,7 @@ import * as guardianPhoneFactorSelectedProvider from './guardianPhoneFactorSelec
 import * as guardianPhoneFactorMessageTypes from './guardianPhoneFactorMessageTypes';
 import * as roles from './roles';
 import * as branding from './branding';
+import * as phoneProviders from './phoneProvider';
 import * as prompts from './prompts';
 import * as actions from './actions';
 import * as triggers from './triggers';
@@ -55,6 +56,7 @@ const auth0ApiHandlers: { [key in AssetTypes]: any } = {
   guardianPhoneFactorMessageTypes,
   roles,
   branding,
+  phoneProviders,
   //@ts-ignore because prompts have not been universally implemented yet
   prompts,
   actions,