HTTPS for localhost client testing

This guide explains how to setup HTTPS for convenient testing and development of OAuth 2.0 web clients (and OpenID relying parties) on a local host.

HTTPS for the web client redirect_uri

Web clients in OAuth 2.0 must register with a non-localhost redirect_uri and the URI should use the https scheme, to ensure the authorisation code and any other parameters sent to it are safe from eavesdropping. The Connect2id server configuration has an option to relax the https strictness for clients in the code flow, but this isn’t recommended due to the security implications.

Example minimal registration for a web client:

POST /clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "redirect_uris" : [ "https://myapp.example.com/callback" ]
}

Setup steps

To test a web OAuth client you can still use a localhost deployment, provided you have administrator (superuser) permissions to modify the local lookup table for hostnames.

The example below assumes that you have a web application at https://myapp.example.com with a redirect_uri at https://myapp.example.com/callback.

Edit the /etc/hosts configuration file which defines a static lookup table for hostnames. Add the following line to set a myapp.example.com hostname for the loopback IP:
```
127.0.0.1    myapp.example.com
```
The OS will now use this entry to resolve the hostname for myapp.example.com, and that also includes DNS requests from the web browser.

Navigate your browser to http://myapp.example.com/ to verify that the lookup works as expected.
Create a self-signed X.509 certificate for myapp.example.com and make it available together with its private key to your local web server where the client application is deployed.

Note that the host name must go into the Common Name (server FQDN) field of the certificate.

If you have OpenSSL, /etc/ssl/private/ as the directory for the private keys and /etc/ssl/certs/ for the certificates the command will be:
```
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/myapp-example-com.key -out /etc/ssl/certs/myapp-example-com.crt
```
When prompted for the Common Name enter the hostname:
```
Common Name (e.g. server FQDN or YOUR name) []:myapp.example.com
```
Edit your web server configuration to enable SSL with the configured certificate and restart it for the configuration to take effect.
Navigate your web browser, this time to the HTTPS URL: https://myapp.example.com

The browser will display a warning that the server certificate is not signed by a recognised Certificate Authority (CA). Add an exception for the domain and continue.

Tips and caveats

1. Client jwks_uri

If the local OAuth 2.0 web client needs to register a jwks_uri endpoint with the Connect2id server the method suggested here will not work. That’s because the /etc/hosts lookup table is used by the OS only and has no effect beyond the local host.

You can however deploy the Connect2id server locally and give its own /etc/hosts entry, for example:

127.0.0.1   c2id.example.com

The client and the server will then be able resolve their IPs and talk to one another via the loopback IP.

2. Shadowing a public hostname

The /etc/hosts table can also be used to shadow a hostnames resolved via the public DNS. That’s because the OS will first check the /etc/hosts table and then any configured DNS servers (unless the OS name service switch is configured otherwise).