Skip to content

Authenticate HTTPs tunnels

Built-in HTTP Authentication

This page applies to inlets-pro 0.10.0 and onwards.

Services exposed over HTTP tunnels can have additional authentication added to them using a mechanism built-into inlets.

The inlets-pro http command provides three options:

  1. Basic Authentication
  2. Bearer Token Authentication
  3. OAuth

You may also be interested in IP filtering, which is configured on the server. This restricts access to a provided set of source IPs or CIDRs.

Basic Authentication

Basic authentication is a simple way to restrict access to your service by requiring a username and password.

When a user visits the URL of the service in a web-browser, they will be prompted to enter a username and password.

If they're using curl, then they can pass the username and password using the --user flag.

curl --user username:password https://example.com

Or simply pass the username and password as part of the URL:

curl https://username:password@example.com

The username has a default of admin for brevity, but can be overridden if you like:

inlets-pro http client \
    --basic-auth-username admin \
    --basic-auth-password password \

You can generate a string password using the openssl command:

openssl rand -base64 32

Bearer Token Authentication

If you're exposing an endpoint that does not need to be accessed via a web-browser, then you can use Bearer Token Authentication.

This is useful for exposing endpoints that are used by mobile apps or other non-web clients.

To enable Bearer Token Authentication, you can use the --bearer-token flag when starting the inlets-pro http command.

inlets-pro http client \
    --bearer-token token \

Both Bearer Token and Basic Authentication can be used together by supplying both flags.

inlets-pro http client \
    --bearer-token token \
    --basic-auth-username admin \
    --basic-auth-password password \

OAuth

With OAuth:

  • You can define access for multiple users using usernames or email addresses
  • Avoid managing credentials in your application
  • Use an existing well-known provider for authentication such as GitHub

Supported providers are GitHub, Google and Signet.

The OAuth 2.0 flow requires a web-browser, so if you anticipate mixed use, then you can combine it with Bearer Token Authentication, for headless clients.

The tunnel client currently has three reserved paths for OAuth: - /_/oauth/login hosts the login page. - /_/oauth/logout can be used to log out. - /_/oauth/callback is used for the OAuth 2.0 callbacks.

Paths prefixed with /_/oauth can not be used by the tunneled service.

Example with GitHub.com

The example below will expose: http://127.0.0.1:3000 using the domain name tunnel.example.com.

In order to use GitHub as the OAuth provider, you need to create a new OAuth application.

  1. Go to GitHub Developer Settings
  2. Click on "New OAuth App"
  3. Enter a name for the application, for example inlets-tunnel
  4. Enter the callback URL, for example http://tunnel.example.com/_/oauth/callback
  5. Click on "Register application"
  6. Click "Generate a new client secret"

You will be given a client ID and client secret, which you can use to authenticate with GitHub.

We suggest saving this in a convenient location, for example: ~/.inlets/oauth-client-id and ~/.inlets/oauth-client-secret.

inlets-pro http client \
    --oauth-client-id $(cat ~/.inlets/oauth-client-id) \
    --oauth-client-secret $(cat ~/.inlets/oauth-client-secret) \
    --upstream tunnel.example.com=http://127.0.0.1:3000 \
    --oauth-provider github \
    --oauth-acl alexellis \
    --oauth-acl name@example.com

Access to the tunnel can be controlled using the --oauth-acl flag. Users can be filtered by username and email.

Tunnels using a commercial inlets license can also control access based on organisation membership. Providing the flag --oauth-acl=org:inlets would allow all users that are a member of the inlets GitHub organisation to access the tunnel.

Once authenticated, a cookie will be set on the domain i.e. tunnel.example.com and the user will be redirected back to the root URL of the service /.

The duration of the cookie defaults to 1 hour, but can be extended through the --oauth-cookie-ttl flag i.e.

inlets-pro http client \
+  --oauth-cookie-ttl 24h \

Example with Google

To use the Google provider you need a commercial Inlets license.

  1. Setup a new project in the Google API console

  2. Configure the project OAuth consent screen.

    Follow the steps to configure the OAuth consent screen.

    If you are a Google Workspace user you can make your app available to any user within your organization by registering it as an internal app.

  3. Create a new OAuth client

    Create a new OAuth client with the application type Web Application. Fill out the name and add the callback URL for your tunnel to the list of valid redirect URIs.

    Example of a redirect uri: http://tunnel.example.com/_/oauth/callback. The callback for a tunnel is always available at /_/oauth/callback.

    Example of a Google OAuth client configuration

  4. Save the Client ID and Client secret in a convenient place so they can be used when connecting the tunnel.

Connect the client:

inlets-pro http client \
    --upstream tunnel.example.com=http://127.0.0.1:3000 \
    --oauth-client-id $(cat ~/.inlets/oauth-client-id) \
    --oauth-client-secret $(cat ~/.inlets/oauth-client-secret) \
    --oauth-provider google \
    --oauth-acl example@gmail.com

You can control which users are allowed to access the tunnel by providing an email address using the --oauth-acl flag.

Example with Signet

The example below will expose http://127.0.0.1:3000 using the domain name tunnel.example.com, with Signet running at https://signet.example.com.

  1. Deploy Signet

    Follow the Signet documentation to install Signet and configure its issuer URL. The issuer must use HTTPS and be reachable by both the tunnel client and users' browsers.

  2. Create a user and an OAuth client

    Follow Provisioning identities to install the Signet CLI and configure its admin credentials. Then create a user and register a client for the tunnel:

    signet user add alice --groups developers
signet client add --redirect-url https://tunnel.example.com/_/oauth/callback inlets-tunnel

    Save the generated user password and client secret. The callback URL must match the public URL of your tunnel, followed by /_/oauth/callback.

  3. Save the client credentials

    Save the client ID (inlets-tunnel) in ~/.inlets/oauth-client-id and the generated client secret in ~/.inlets/oauth-client-secret.

Connect the client, adding your existing tunnel server --url and --token-file flags:

inlets-pro http client \
    --upstream tunnel.example.com=http://127.0.0.1:3000 \
    --oauth-client-id $(cat ~/.inlets/oauth-client-id) \
    --oauth-client-secret $(cat ~/.inlets/oauth-client-secret) \
    --oauth-provider signet \
    --oauth-issuer-url https://signet.example.com \
    --oauth-acl group:developers

The --oauth-issuer-url flag is required for Signet and must match the Signet URL.

You can control which users are allowed to access the tunnel with the --oauth-acl flag:

  • --oauth-acl alice@example.com allows a user with that email address.
  • --oauth-acl alice allows a user with that subject (sub) claim. For Signet, this is the username.
  • --oauth-acl group:developers allows any user in the developers group.

Repeat --oauth-acl to allow multiple users or groups. A user only needs to match one entry. If no entries are provided, access is denied to all users.

Visit https://tunnel.example.com in a web-browser and sign in with the Signet user created above. Once authenticated, users matching the ACL can access the tunneled service.

See Provisioning identities for managing users, groups and OAuth clients with the Signet CLI or admin API.

More providers will be added over time, based upon requests from users, so if you want to use Facebook, GitLab, etc, send us an email to help with prioritisation.