jwt-auth-service

Running the App

Note: Currently, this has not been optimized for security or tailored for a production environment yet.

Environment Variables

There are some default environment variables set in the docker-compose.yml file, some of the optional and/or secret variables are not currently in there and would have to be manually added to the file and/or to the machine. See below for a full list of supported environment variables.

Some of the below variables are specific to either the generating of the JWT or used as claims within the JWT. Please see the following RFC for detains on the various supported claims - https://tools.ietf.org/html/rfc7519#section-4

Environment Variable	Example Value	Notes
MONGO_PORT	27017	The port that the app will use to attempt to connect to mongo on.
MONGO_HOST	mongodb | 172.16.X.X	The address that the app will use to attempt to connect to mongo. If connecting to an instance of mongo not in the docker-compose stack, i.e. not in the local network with the running GoLang app, you also need to set the following env vars; MONGO_USERNAME, MONGO_PASSWORD, MONGO_AUTH_SOURCE.
MONGO_DB_NAME	authservice	The name of the mongo database the service will use for all of its transactions.
MONGO_USERNAME	auth_service_user	Username used to authenticate with mongo.
MONGO_PASSWORD	auth_5erv1ce_p4ssw0rd	Password used to authenticate with mongo.
MONGO_AUTH_SOURCE	admin	The database within mongo that is holding username/password credentials to allow connections, likely defaulted to admin.
BCRYPT_COST_FACTOR	12	The Default value/minimum the service will accept is 10, max value is 31. Prefer: 12 | Example: Cost of 12 = 200ms Response time, every cost increase of 1 roughly doubles response time.
JWT_SECRET	jwt_5ecr3t	Secret used for generating and verifying JWT signatures. See https://jwt.io for more information on all things to do with JWTs.
JWT_TTL	15	Time to live in minutes for the token, the tokens generated by this service will be considered expired after this time has passed and will fail any validation checks from that point forward. Provide 0 for a token with no expiry but I highly advise against this as the TTL is the main defence against JWT hijacking.
JWT_ISS	jwt.auth.example.com | MyJWTServiceV1	(Optional) ISS or Issuer is a claim used to identify the service that is issuing the JWT (i.e this service) and is generally application specific. The consuming application should check this is as you expect and can be any string or URI. This is to be used mainly as an extra bit of security for the consumers of the tokens.
JWT_AUD	consumer.example.com,myWebAppOne,myWebAppTwo	(Optional) AUD or Audience is a claim specifying the intended consumers of the JWTs generated by the service. This can be an array of strings or URIs representing the intended audiences. This is to be used mainly as an extra bit of security for the consumers of the tokens.
CERT_DOMAINS	example.com,test.example.com,example.org	A comma separated list of domains that autotls will attempt to create certificates for and run the application against. Only exact matches are supported, as an example, *.example.com will not have a certificate generated for all sub domains.
GIN_MODE	release | debug | test	Set the mode for GIN to use.
DEBUG	true | false	Not currently used.

Run Local:

Note: The App requires a mongo connection to run, so either start a local instance of mongo or run mongo within a docker container and ensure that all of the mongo connection details are set as ENV vars or in the .env file.

Setting up environment variables

Either fill in all of the required environment variables within the .env file at the parent of this directory, or set the required environment variables on the local machine the app will be running on.

If you are using the .env file to populate environment variables, add the following code to the top of main.go:

// Load .env file, this is for locally running the app only
err := godotenv.Load()
if err != nil {
	log.Fatal("error loading .env file")
}

Running the App

go run .

Running with Docker Containers

Building the App Docker image

First we must build the image, once built we can call run on it. From the root directory of this project run the following.

docker build .

Tagging the image to push to an image repository

Below we are supplying -t, tagging it as /jwt-auth-service: where username is your dockerhub or other image repository name. You can tag it multiple times, allowing you to publish a new version also as the latest tag, below we are tagging as both v1.0 and latest.

This step isn't strictly needed unless you plan on modifying the image and pushing it to a repository to pull and use multiple times.

docker build -t <username>/jwt-auth-service:v1.0 -t <username>/jwt-auth-service:latest .

Running a MongoDB container

First we need to start a container running docker.

docker run -p 27017:27017 --name mongoc -v /ProgramData/DockerStore:/DockerResources/data/mongodb mongo

Running the App Docker image

Then we can run the docker container for this service. Remember, you may need to change some environment variables and feed them in to the container.

docker run -p 8080:8080 --detach --name auth-service <username>/jwt-auth-service

Mongo-Express - Tool for viewing MongoDB data/Schema

Optionally, you can run mongo-express which is a web GUI for the mongoDB container we have running.

docker run -it --rm -p 8081:8081 --link mongoc:mongo mongo-express

Running with Docker-Compose:

> docker-compose build
> docker-compose up

The stack will come up with 3 containers running:

• authservice (Running the build Go binary)
• mongodb (The database container)
• mongoex (mongo-express to allow viewing mongo via browser frontend)

Note: The names above are based on the container names specified in the docker-compose.yml file.

The mongo-express container is not required for the service to function, I have included it in the stack to make my life a bit easier while testing/developing. If not needed, it should probably be removed and not spun up with the rest of the stack.

Notes

Invoke API via cURL

curl -X POST -H "Content-Type: application/json" \
    -d '{"username":"test_0001","password":"qwerty","email":"test@example.com"}' \
    http://localhost:8080/api/v1/user/register

curl -X POST -H "Content-Type: application/json" \
    -d '{"username":"test_0001","password":"qwerty"}' \
    http://localhost:8080/api/v1/user/login

TOKEN="" \
    curl -X GET -H "Authorization: Bearer ${TOKEN}" \
    http://localhost:8080/api/v1/token/validate

Invoke API via PowerShell

Invoke-WebRequest http://localhost:8080/api/v1/user/register `
    -UseBasicParsing `
	-ContentType "application/json" `
	-Method POST `
	-Body '{"username":"test_0001","password":"qwerty","email":"test@example.com"}' | Select-Object -expand RawContent

Invoke-WebRequest http://localhost:8080/api/v1/user/login `
    -UseBasicParsing `
	-ContentType "application/json" `
	-Method POST `
	-Body '{"username":"test_0001","password":"qwerty"}' | Select-Object -expand RawContent

$token = ""
Invoke-WebRequest http://localhost:8080/api/v1/token/validate `
    -UseBasicParsing `
	-Method GET `
	-Header @{Authorization = "Bearer $token"}

TODO

See the TODO file in the root of the repository.