Visual Studio Team Services Deployments

The Visual Studio Team Services Deployments extension allows you to deploy rules, rules configs, hooks, connections, database connection scripts, clients, client grants, resource servers, Universal Login pages, and email templates to Auth0 from Visual Studio Team Services. You can configure a Visual Studio Team Services project, keep all of your scripts there, and have them automatically deployed to Auth0 each time you push changes to your project.

To install this extension:

Navigate to the Extensions page of the Auth0 Dashboard, and click the Visual Studio Team Services Deployments box. The Install Extension window opens.
Set the following configuration parameters:

TYPE: The type of repository; choose from TFVC or Git.
REPOSITORY: The project from which you want to deploy your rules and database scripts. To use a specific repository within a project, format your input value as follows: projectName/repoName.
BRANCH: The branch the extension will monitor for changes.
INSTANCE: Your Visual Studio Team Services instance name (without .visualstudio.com).
COLLECTION: Your Visual Studio collection (DefaultCollection for Azure DevOps).
USERNAME: Your Visual Studio Team Services username
TOKEN: Your personal Access Token for Visual Studio Team Services. To learn how to configure a token, see Microsoft's Create a Personal Access Token.
BASE_DIR: The base directory, where all your tenant settings are stored.
AUTO_REDEPLOY: If enabled, the extension redeploys the last successful configuration in the event of a deployment failure. Manual deployments and validation errors do not trigger auto-redeployment.
AUTH0_ALLOW_DELETE: When enabled, the extension is allowed to delete objects that do not exist within the repository.
SLACK_INCOMING_WEBHOOK_URL: The specific Slack webhook to which you want to send reports from the extension.

Some of the configuration variables were changed in version 2.5.0 of this extension. If you are updating the extension from a prior version, make sure that you update your configuration accordingly.

Once you have provided this information, click Install.

Because the extension will communicate with your Visual Studio Team Services account on your behalf, you will need to authorize its access.

To authorize the extension:

If you're following this guide, you should already be on the Installed Extensions view of the Extensions page of the Auth0 Dashboard. Click Visual Studio Team Services Deployments to launch the extension. A consent dialog will appear, requesting access to your Visual Studio Team Services account.
Consent to allow the extension to access your account. After you consent, the extension launches, and you are redirected to the Visual Studio Team Services Integration page.

After the extension is installed, you should configure the extension settings. To configure the extension:

If you're following this guide, you should already have launched the extension and been redirected to the Visual Studio Team Services Integration page. Click the Configuration tab.
Copy the values for the Payload URL and HTTP headers displayed on this page. You must use these values when configuring a Webhook for your Visual Studio Team Services project. To learn more, see Microsoft's Integrate with service hooks documentation.

Once you have set up the webhook in Visual Studio Team Services, you are ready to start committing to your project.

With each commit you push to your configured Visual Studio Team Services project, the webhook will call the extension, which will initiate a deployment if changes were made to one of these folders:

clients
grants
emails
resource-servers
connections
database-connections
rules-configs
rules
pages

To manually deploy the Rules and Database Connection scripts that you already have in your Visual Studio Team Services project, use the Deploy button on the Deployments tab of the extension. This is useful if your repository already contains items that you want to deploy after you have set up the extension, or if you have accidentally deleted some scripts in Auth0 and need to redeploy the latest version of your repository.

To maintain a consistent state, the extension will always do a full deployment of the contents of these folders. Any rules or database connection scripts that exist in Auth0 but not in your repository (or project) will be deleted.

When AUTH0_ALLOW_DELETE is set to yes, existing settings are deleted only when corresponding folders are present and contain configuration files. Settings are not be deleted for missing or empty folders.

This works for only non-Auth0 connections (strategy !== auth0). For Auth0 connections, use database-connections.

To deploy a connection, create a JSON file under the connections directory in your Visual Studio Team Services project. For example:

facebook.json

{
  "name": "facebook",
  "strategy": "facebook",
  "enabled_clients": [
    "my-client"
  ],
  "options": {}
}

Was this helpful?/

The enabled_clients array, when used directly with the Management API v2, is a list of client IDs for which the connection is enabled. As an added convenience, the deployment extension will attempt to match entries in the enabled_clients array by client name and replace them with the appropriate client ID when a match is found, allowing you to specify "my-client-name" instead of "my-client-id" to refer to each application.

To learn more about the allowed attributes for connections, see Auth0's Management API Post Connections endpoint.

This works for only Auth0 connections (strategy === auth0) . For non-Auth0 connections, use connections.

To deploy a database connection, create a subdirectory named [connection-name] under the database-connections directory in your Visual Studio Team Services project. The name of the subdirectory must exactly match the name of your database connection in Auth0. You can create as many subdirectories as you have database connections.

Create a JSON file named database.json under the corresponding database-connections/[connection-name] subdirectory in your Visual Studio Team Services project.

Support for using settings.json rather than database.json has been deprecated since extension v3.1.1 and may be dropped in a future release.

To learn more about allowed attributes for connections, see Auth0's Management API Patch Connections by ID endpoint.

To deploy a database connection script, create a JavaScript file under the corresponding database-connections/[connection-name] subdirectory in your Visual Studio Team Services project. The filename of the JavaScript file should correspond to the database connection script you want to deploy.

Allowed scripts include:

get_user.js
create.js
verify.js
login.js
change_password.js
delete.js

For a generic custom database connection, only the login.js script is required. However, if you enable the migration feature, you will also need to provide the get_user.js script.

To see examples, visit the Auth0 Samples GitHub repository. While the samples were authored for GitHub, they will work for a Visual Studio Team Services integration too.

Supported pages include:

error_page
guardian_multifactor
login
password_reset

To deploy a page, create an HTML file under the pages directory in your Visual Studio Team Services project. For each HTML page, you must also create a JSON file (with the same name) that controls whether the page is enabled or disabled.

For example, to deploy a password_reset page, you would create two files:

your-vsts-project/pages/password_reset.html your-vsts-project/pages/password_reset.json

To enable the page, the password_reset.json would contain the following:

{
  "enabled": true
}

Was this helpful?/

The error_page cannot be enabled/disabled. To use the default error page, remove the content of error_page.html.

To deploy a rule, create a JavaScript file under the rules directory in your Visual Studio Team Services project. Each rule must be contained in its own JavaScript file. For each JavaScript file, you must also create a JSON file (with the same name) that controls the rule order, status, and stage during which the rule executes.

If you plan to use source control integration for an existing account, first rename your Rules in Auth0 to match the name of the files you will be deploying to this directory.

For example, to deploy a set-country rule, you would create two files:

your-vsts-project/rules/set-country.js your-vsts-project/rules/set-country.json

set-country.js

function (user, context, callback) {
  if (context.request.geoip) {
    user.country = context.request.geoip.country_name;
  }
  callback(null, user, context);
}

Was this helpful?/

set-country.json

{
  "enabled": false,
  "order": 15,
  "stage": "login_success"
}

Was this helpful?/

To see an example for the login_success stage, visit the Auth0 Samples GitHub repository. While the sample was authored for GitHub, it will work for a Visual Studio Team Services integration too.

To avoid conflicts, multiple rules with the same order are not allowed. However, you can create a JSON file for each rule, and within each file, assign a value for order. We suggest using number values that allow for reordering with less risk of conflict. For example, assign a value of 10 to the first Rule and 20 to the second Rule, rather than using values of 1 and 2, respectively.

Once you deploy a rule, you cannot change the stage during which the rule executes.If you need the rule to execute during a different stage, you must create a new rule configured for that stage and delete the original rule.

Only one rule may execute during the user_registration and login_failure stages.

To deploy a rule config, create a JSON file under the rules-configs directory in your Visual Studio Team Services project. For example:

secret_number.json

{
  "key": "secret_number",
  "value": 42
}

Was this helpful?/

To deploy a client, create a JSON file under the clients directory in your Visual Studio Team Services project. For example:

my-client.json

{
  "name": "my-client"
}

Was this helpful?/

To learn more about allowed attributes for clients and client grants, see Auth0's Management API Post Clients endpoint.

To specify the client grants for each client, create a JSON file under the grants directory in your Visual Studio Team Services project. For example:

my-client-api.json

{
  "client_id": "my-client",
  "audience": "https://myapp.com/api/v1",
    "scope": [
      "read:users"
    ]
}

Was this helpful?/

The deployment extension accepts an application name instead of the client ID in the client_id property. It will try to match the name to an existing application before creating the Client Grant.

To deploy a resource server, create a JSON file under the resource-servers directory in your Visual Studio Team Services project. For example:

my-api.json

{
  "name": "my-api",
  "identifier": "https://myapp.com/api/v1",
  "scopes": [
    {
      "value": "read:users",
      "description": "Allows getting user information"
    }
  ]
}

Was this helpful?/

To learn more about allowed attributes for resource servers, see Auth0's Management API Post Resource Servers endpoint.

To deploy an email provider, create a provider.json file under the emails directory in your Visual Studio Team Services project. For example:

provider.json

{
    "name": "smtp",
    "enabled": true,
    "credentials": {
        "smtp_host": "smtp.server.com",
        "smtp_port": 25,
        "smtp_user": "smtp_user",
        "smtp_pass": "smtp_secret_password"
    }
}

Was this helpful?/

To learn more about allowed attributes for email providers, see Auth0's Management API Patch Provider endpoint.

Supported email templates include:

verify_email
reset_email
welcome_email
blocked_account
stolen_credentials
enrollment_email
mfa_oob_code

To deploy an email template, create an HTML file under the emails directory in your Visual Studio Team Services project. For each HTML file, you must also create a JSON file (with the same name) that contains additional options for that template.

For example, to deploy a blocked_account template, you would create two files:

your-vsts-project/emails/blocked_account.html your-vsts-project/emails/blocked_account.json

blocked_account.json

{
    "template": "blocked_account",
    "from": "",
    "subject": "",
    "resultUrl": "",
    "syntax": "liquid",
    "body": "./blocked_account.html",
    "urlLifetimeInSeconds": 432000,
    "enabled": true
}

Was this helpful?/

You can exclude the following records from the deployment process:

rules
clients
databases
connections
resourceServers

If excluded, records will not be modified by deployments.

Dashboard - Extensions - Deploy Extension - Excluded Rules

Beginning with version 3.0.0, you can manage your secrets and tenant-based environment variables using keyword mappings. This is useful if you want to specify different variables across your environments. For example, you could specify different JWT timeouts for your Development, QA/Testing, and Production environments.

To use keyword mappings, either wrap the key using:

@ symbols (e.g., @@key@@), which will cause your value to be converted from a Javascript object or value to a JSON string.
# symbols (e.g., ##key##), which will cause Auth0 to perform a literal replacement.

A sample implementation is as follows:

Client.json

{
  ...
  "callbacks": [
    "##ENVIRONMENT_URL##/auth/callback"
  ],
  "jwt_configuration": {
    "lifetime_in_seconds": ##JWT_TIMEOUT##,
    "secret_encoded": true
  }
  ...
}

Was this helpful?/

Dashboard - Extensions - Deploy Extension - Mappings

To track deployments:

Navigate to the Extensions page of the Auth0 Dashboard, and click Installed Extensions.
Select Visual Studio Team Services Deployments, and click the Deployments tab. You will see a list of all deployments, both successful and failed.

You can view more detail by clicking on a deployment.

If you configured a Slack Incoming Webhook, you will also be notified on Slack when deployments succeed or fail.

Docs