Dev Tunnels is a security-first, developer-optimized tunneling service designed to allow you to securely expose your local endpoint to the internet. This is helpful for sharing in-progress work, testing, and debugging web APIs and webhooks, experimenting on other devices, and testing integrations with cloud services. Dev Tunnels is cross-platform and available through:
Today, we’re excited to walk you through the advantages of Dev Tunnels and provide a step-by-step guide on how to use the devtunnel
CLI. You can either follow along with our Dev Tunnels engineer, Utsa, in the video below, or continue reading for the detailed walkthrough with some bonus tips at the end.
Benefits
- Secure by default: All connections to a tunnel are encrypted and authenticated, ensuring that only you can access the tunnel you create.
- Persistent URLs: Keep the same URL for as long as you need. Please note, they will be automatically deleted after 30 days of inactivity though, or you can set a custom expiration.
- Multi-port hosting: Host multiple ports on a single dev tunnel simultaneously.
- Global availability: The Dev Tunnels service is available globally and your tunnels are automatically created in the nearest available region.
- Traffic inspection: Inspect your tunnel’s traffic using the familiar interface of browser DevTools to aid in your debugging process.
Step 1: Download and install the devtunnel CLI and login
Begin by downloading and installing the devtunnel CLI that corresponds with your operating system. Then, log in using either your Entra ID, Microsoft, or GitHub account. Dev Tunnels doesn’t support anonymous tunnel hosting.
devtunnel user login
Tip: Alternatively, you can log in using a device code login flow by running devtunnel login –d
Step 2: Launch a local server and host or create a tunnel
Once logged in, you can start hosting a dev tunnel using the host command. The command should be run on the host system running the server you want accessible through the dev tunnel.
devtunnel host –p PORT
Note: This will generate a temporary dev tunnel unless a dev tunnel ID is specified. For a persistent tunnel, run devtunnel create
.
A successful host or create command will print out your tunnel ID, the Dev Tunnel URL, and the inspection URL in the console. Congratulations, you’ve just created your first Dev Tunnel! You can now connect to your tunnel by visiting this URL in a web browser and logging in with the same account as you used to host the tunnel.
Step 3: Learn authentication and access control tips
For the following bonus tips, you can either follow along with our Dev Tunnels engineer, Jason, in the video below, or continue reading ahead.
Grant access to your organization
By default, tunnels are only accessible to you. Optionally, you can grant access to your organization. If you’re logged in with your AAD account, you can grant access to everyone in your AAD tenant by running:
devtunnel create
devtunnel access add --tenant
If you’re logged in with your GitHub account, you can grant access to everyone in your org by running:
devtunnel create
devtunnel access add –org <org-name>
Working with app authentication
If the application already has integrated authentication, you might not need that additional layer of access control. In this case, configure the tunnel to allow anonymous connections by appending --anonymous
to the create command. Then the application can be in full control of the client authentication and login flow as needed. Depending on the type of login performed by the application, two additional configuration steps might be necessary. Normally the dev tunnel relay will rewrite the http host header to be localhost because that works better for most applications, but for auth redirection you would need to change that option, so that it will preserve the tunnel DNS name. You can do this by running:
devtunnel update –host-header unchanged
This command ensures that the host header remains unchanged, allowing the application to redirect to the tunnel. You have one more step to after this. You will have to configure the redirect URI as a valid URI in your application. You can see a demo of this here.
Use a client access token
For web API clients, it’s more convenient to connect and authenticate with a tunnel access token. Obtain the dev tunnel access token by creating a tunnel and then using the dev tunnel token command:
devtunnel create
devtunnel token --scope connect
You can now utilize this token in command-line tools like curl or web API testing tools like Postman. The header name `x-tunnel-authorization` is distinct from the standard authorization header to avoid potential conflicts with any application auth. You can see a demo of this here.
Pre-auth a client connection
Instead of having each client authenticate tunnel connections with a login or an access token, it’s possible to forward tunnel ports to a client’s localhost. The devtunnel connect
command establishes a secure authenticated connection to the tunnel relay, allowing client apps to connect to forwarded ports from the tunnel on their localhost. You can see a demo of this here.
Wrapping up
Now that you know the main benefits of Dev Tunnels, how to create and host a tunnel, and authentication and access control tips, you’re ready to boost your productivity when testing and debugging! We’re eager to hear how Dev Tunnels enhances your development process.
We appreciate the time you’ve spent reporting issues/suggestions and hope you continue to give us feedback when using dev tunnels on what you like and what we can improve. Your feedback is critical to help us make dev tunnels the best tool it can be! You can share feedback with us on our GitHub repo here.
Happy tunneling!
0 comments