https with ngrok

While ngrok can be used to expose your local development application to the internet for testing,
the free version of ngrok does not support End-to-End TLS Tunnels aka https, but it does support forwarding of https to http

Note: Transport Layer Security (TLS) is the successor to SSL. TLS 1.0 was defined in RFC 2246 in January 1999.  Hypertext Transfer Protocol Secure (HTTPS), or “HTTP Secure,” is an application-specific implementation that is a combination of the Hypertext Transfer Protocol (HTTP) with the SSL/TLS.
reference: is-it-ssl-tls-or-https

For Single Sing On solutions, such as SAML, you application is required to be hosted over https

You might think you could just bind to the ssl port 443

> ngrok http myawesomeapp.local:443

Session Status                online
Session Expires               7 hours, 4 minutes
Version                       2.2.8
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://8316dcb8.ngrok.io -> myawesomeapp.local:443
Forwarding                    https://8316dcb8.ngrok.io -> myawesomeapp.local:443  

But, accessing https://8316dcb8.ngrok.io or http://8316dcb8.ngrok.io results in the browser showing

Bad Request
Your browser sent a request that this server could not understand.
Reason: You're speaking plain HTTP to an SSL-enabled server port.

So that is why you need the paid version of ngrok for End-to-End TLS Tunnels.

One solution is to pay for the Pro version of ngrok, which also gets you access to more features such as Whitelabel domains, Reserved TCP addresses, End-to-End TLS Tunnels, and more resources.

However, if your using PHP Symfony or the PHP OneLogin SAML library,
another solution is to modify your application to indicate that the request is actually https.

Start up ngrok

> ngrok http myawesomeapp.local:80

Session Status                online
Session Expires               7 hours, 4 minutes
Version                       2.2.8
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://8316dcb8.ngrok.io -> myawesomeapp.local:80
Forwarding                    https://8316dcb8.ngrok.io -> myawesomeapp.local:80  

If you view https://8316dcb8.ngrok.io, you will see your app, but you app will think its running on port 80 and http

Note: While this is PHP focused, the concept should apply to other applications.

To make your app think it's on https, in the bootstrap or initialization of your application, add:

// If the host url has ngrok.io, and the header X-Forwarded-Proto set by ngrok is https, then also set https on and the port to 443
if (strpos($_SERVER['HTTP_HOST'], 'ngrok.io') !== false && $_SERVER['HTTP_X_FORWARDED_PROTO'] == 'https')
{
  $_SERVER['HTTPS'] = 'on';
  $_SERVER['SERVER_PORT'] = 443;
}

Note: For Symfony, you can place this code within the boostrap app_dev.php, above the creation of $request

> vi app_dev.php

// place here

$request = Request::createFromGlobals();
$response = $kernel->handle($request);


This will allow any following code which checks for https
such as OneLogins Utils::isHTTPS()
or Symfony Request->isSecure()
to return true when accessing the ngrok url over https

Note: This does not test or affect your applications ssl certs, as the browser thinks the request is from 8316dcb8.ngrok.io,  And if you are using ngrok daily for development or testing, it is fairly inexpensive to upgrade to the tls version which is a  simpler and better solution

Hopefully this helps you test Single Sing On solutions, such as SAML.

-End of Document-

Thanks for reading

ngrok - expose a local server to the internet

• Whats is ngrok?

ngrok provides introspected tunnels to localhost.
ngrok is a reverse proxy that creates a secure tunnel from a public endpoint to a locally running web service.

Which translates to
"I want to expose a local server to the internet"
http://anyonecanaccess -> http://localhost

• Why would you want to use ngrok?

ngrok can be necessary for development and testing external services, such as Single Sign On, SAML, external APIs, Cloud solutions, etc
While you could pay for a domain and forward that to your development environment, that tends to be cost prohibitive and not overly practical given the nature of development and testing vms, containers, services, etc.  Especially in a company environment where you do not have access to the routers/firewalls.

You can also use ngrok to quickly demo a local feature before deploying.

• How to use ngrok

To use ngrok, download and extract it to a directory
https://ngrok.com/download
C:/dev/ngrok

From a command prompt,
such as microsofts cmd or a more feature rich ConsoleZ

> ngrok http 80

Session Status         online
Session Expires        7 hours, 4 minutes
Version                2.2.8
Region                 United States (us)
Web Interface          http://127.0.0.1:4040
Forwarding             http://24f98db7.ngrok.io -> localhost:80
Forwarding             https://24f98db7.ngrok.io -> localhost:80  

Assuming you already have a web based application running on port 80 ie
http://localhost
you can access your local development environment via
http://24f98db7.ngrok.io
The '24f98db7' part is randomly generated every time you start an ngrok instance.

The free version doesn't require an account and allows for basic http/tcp tunnels, which tends to be sufficient for development.  But the publicly exposed url is limited to 8 hours.  You can also create a free account for more resources if needed.

The paid versions of ngrok allow for End-to-End TLS Tunnels, Reserved domains, Reserved TCP addresses, more connections / minute, more tunnels/ngrok process, etc.

If your local development application runs on a custom local domain name such as myawesomeapp.local, you can use that with ngrok instead of localhost

> ngrok http myawesomeapp.local:80

Session Status                online
Session Expires               7 hours, 4 minutes
Version                       2.2.8  
Region                        United States (us)      
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://8316dcb8.ngrok.io -> myawesomeapp.local:80
Forwarding                    https://8316dcb8.ngrok.io -> myawesomeapp.local:80      

Note: Unlike .local, .test, and .example, .dev is not on a list of specially protected names.
in 2017, Chrome forces connections to all domains ending in .dev (as well as .foo) to use HTTPS
reference: theregister goole dev network

You can also add basic password protection to your exposed application

> ngrok http -auth "user:password" myawesomeapp.local:80

To stop ngrok just press ctrl + c

ngrok away

-End of Document-

Thanks for reading