This JWT Auth Proxy is a lightweight authentication proxy written in Go designed for use in Docker/Kubernetes environments.

JWT Auth Proxy sits between your frontend and your application's backend, handles authentication, and proxies authenticated requests to your backend. It offers REST APIs and logic for signup (incl. double-opt-in), password reset ("forgot my password") and verified email address change. This way, your application's backend can focus on the actual business logic, while relying on secure authentication having been performed before.

To your application's backend, the JWT Auth Proxy provides an mTLS-secured REST API for modifying user objects and storing custom data per user.

JWT Auth Proxy uses short-lived JWT access tokens (HMAC-signing with SHA-512) and long-lived UUIDv4 refresh tokens for securely retrieving new access tokens before the old one expires.

• Easy-to-use REST API for
  • Signup with double-opt-in
  • Login
  • Logout
  • Password reset (forgot password)
  • Email address change with double-opt-in
  • JWT access token renewal using long-lived refresh tokens
• Proxy authenticated requests to your application's backend
• Whitelist backend URLs not requiring authentication

• mTLS encrypted connecting (mutual TLS)
• Easy-to-use REST API for
  • Create user
  • Delete user
  • Disable/enable user
  • Check password
  • Set password
  • Set email address
  • Store and retrieve custom per-user data (JSON)

Prerequisites: A MongoDB instance (tested with MongoDB v4).

Please refer to the docker-compose.yml example on how to use the pre-build Docker image.

The server requires a key and a certificate for providing mTLS encryption for the backend REST API.

To generate the server's key and certificate:

mkdir -p /opt/docker/jwt-auth-proxy/certs/server cd /opt/docker/jwt-auth-proxy/certs # Generate the server key and cert openssl genrsa -out server/server.key 4096 openssl req -new -x509 -sha256 -key server/server.key -out server/server.crt -days 3650 # Prepare serial for client certificate signing echo "00" > server/server.srl 

To generate client key and self-signed certificate:

mkdir -p /opt/docker/jwt-auth-proxy/certs/clients cd /opt/docker/jwt-auth-proxy/certs # Generate client key and certicate signing request: openssl genrsa -out clients/client1.key 4096 openssl req -new -key clients/client1.key -out clients/client1.csr # Sign the certificate with the server's key: openssl x509 -req -in clients/client1.csr -CA server/server.crt -CAkey server/server.key -CAserial server/server.srl -out clients/client1.crt 

When your application's backend receives an HTTP request proxied through the JWT Auth Proxy, it receives all the HTTP request headers sent by the HTTP client/browser, plus:

• Authorization: The successfully validated JWT access token (format: Bearer <Token>).
• X-Auth-UserID: The user's ID you can use to make calls to the backend-facing REST API.
• Forwarded: Information from the client-facing side of the proxy server.
• X-Forwarded-For (XFF): The originating IP address of the client.
• X-Forwarded-Host (XFH): The original host requested by the client in the Host HTTP request header.
• X-Forwarded-Proto (XFP): The protocol (HTTP or HTTPS) the client used to connect to the proxy.

• Use Case: Sign up a new user using his unique email address as the username.
• URL: /auth/signup
• Method: POST
• JSON Payload:

  { "email": "<User's email address = username>", "password": "<User's chosen password (min length = 8, max length = 32)>" } 

• HTTP Response Status Codes:
  • 201: Created (user successfully signed up, User ID in response header 'X-Object-ID')
  • 400: Bad request (invalid JSON payload)
  • 409: Conflict (user already exists)

• Use case: Log in activated and enabled user, retrieve Access and Refresh Tokens.
• URL: /auth/login
• Method: POST
• JSON Payload:

  { "email": "<User's email address = username>", "password": "<User's chosen password (min length = 8, max length = 32)>" } 

• HTTP Response Status Codes:
  • 200: OK (user successfully logged in, result in response body payload)
  • 400: Bad request (invalid JSON payload)
  • 401: Unauthorized (authorization failed due to various reasons)
• HTTP Response Body:

  { "accessToken": "<short-lived JWT Access Token>", "refreshToken": "<long-lived UUIDv4 Refresh Token>", } 

• Use case: Renew short-lived Access Token with long-lived Refresh Token.
• URL: /auth/renew
• Method: POST
• Request Header: Authorization: Bearer <Access Token>
• JSON Payload:

  { "renewToken": "<long-lived UUIDv4 Refresh Token from login>" } 

• HTTP Response Status Codes:
  • 200: OK (successful, result in response body payload)
  • 400: Bad request (invalid JSON payload)
  • 401: Unauthorized (authorization failed due to various reasons)
• HTTP Response Body:

  { "accessToken": "<short-lived JWT Access Token>", "refreshToken": "<long-lived UUIDv4 Refresh Token>", } 

• Use case: Invalidate Refresh Token.
• URL: /auth/logout
• Method: POST
• Request Header: Authorization: Bearer <Access Token>
• JSON Payload:

  { "renewToken": "<long-lived UUIDv4 Refresh Token from login>" } 

• HTTP Response Status Codes:
  • 201: No content (successful)
  • 400: Bad request (invalid JSON payload)
  • 401: Unauthorized (authorization failed due to various reasons)

• Use case: Check if Access Token is still valid.
• URL: /auth/ping
• Method: GET
• Request Header: Authorization: Bearer <Access Token>
• HTTP Response Status Codes:
  • 201: No content (successful)
  • 401: Unauthorized (authorization failed due to various reasons)

• Use case: User wants to confirm a requests received via email (such as signup, password reset, email change)
• URL: /auth/confirm/<ID from email>
• Method: POST
• HTTP Response Status Codes:
  • 201: No content (successful)
  • 404: Not found (invalid, expired or already confirmed ID)

• Use case: Logged in user wants to change his password.
• URL: /auth/setpw
• Method: POST
• Request Header: Authorization: Bearer <Access Token>
• JSON Payload:

  { "oldPassword": "<user's old password>", "newPassword": "<user's new password>" } 

• HTTP Response Status Codes:
  • 201: No content (successful)
  • 400: Bad request (invalid JSON payload)
  • 401: Unauthorized (authorization failed due to various reasons)

• Use case: Logged in user wants to change his email address (= username).
• URL: /auth/changeemail
• Method: POST
• Request Header: Authorization: Bearer <Access Token>
• JSON Payload:

  { "password": "<user's password>", "email": "<user's new email address>" } 

• HTTP Response Status Codes:
  • 201: No content (successful, email sent to new email address - confirmation required before new address gets activated)
  • 400: Bad request (invalid JSON payload)
  • 401: Unauthorized (authorization failed due to various reasons)
  • 409: Conflict (email address already exists)

• Use case: User forgot his password and wants to reset it.
• URL: /auth/initpwreset
• Method: POST
• JSON Payload:

  { "email": "<user's email address>" } 

• HTTP Response Status Codes:
  • 201: No content (successful, email sent user - confirmation required before new password is generated)
  • 400: Bad request (invalid JSON payload)

• Use case: User wants to delete his own account.
• URL: /auth/delete
• Method: POST
• Request Header: Authorization: Bearer <Access Token>
• JSON Payload:

  { "password": "<user's password>" } 

• HTTP Response Status Codes:
  • 201: No content (successful)
  • 400: Bad request (invalid JSON payload)
  • 401: Unauthorized (authorization failed due to various reasons)

• Use case: Create a new user.
• URL: /users/
• Method: POST
• JSON Payload:

  { "email": "<user's email address>", "password": "<User's password (min length = 8, max length = 32)>", "confirmed": true|false, "enabled": true|false, "data": {} } 

• HTTP Response Status Codes:
  • 201: Created (user successfully created, User ID in response header 'X-Object-ID')
  • 400: Bad request (invalid JSON payload)
  • 409: Conflict (email address already exists)

• Use case: Get a user object.
• URL: /users/<ID>
• Method: GET
• HTTP Response Status Codes:
  • 200: OK (successful, result in response body payload)
  • 404: Not found (invalid User ID)
• HTTP Response Body:

  { "email": "<user's email address>", "password": "<User's password (min length = 8, max length = 32)>", "confirmed": true|false, "enabled": true|false, "data": {} } 

• Use case: Delete a user.
• URL: /users/<ID>
• Method: DELETE
• HTTP Response Status Codes:
  • 204: No content (successful)
  • 404: Not found (invalid User ID)

• Use case: Set a user's email address.
• URL: /users/<ID>/email
• Method: PUT
• JSON Payload:

  { "email": "<user's email address>" } 

• HTTP Response Status Codes:
  • 204: No content (successful)
  • 400: Bad request (invalid JSON payload)
  • 404: Not found (invalid User ID)
  • 409: Conflict (email address already exists)

• Use case: Set a user's password.
• URL: /users/<ID>/password
• Method: PUT
• JSON Payload:

  { "password": "<user's new password>" } 

• HTTP Response Status Codes:
  • 204: No content (successful)
  • 400: Bad request (invalid JSON payload)
  • 404: Not found (invalid User ID)

• Use case: Disable a user account so that the user can't log in anymore.
• URL: /users/<ID>/disable
• Method: PUT
• HTTP Response Status Codes:
  • 204: No content (successful)
  • 404: Not found (invalid User ID)

• Use case: Enable a user account so that the user can log in.
• URL: /users/<ID>/enable
• Method: PUT
• HTTP Response Status Codes:
  • 204: No content (successful)
  • 404: Not found (invalid User ID)

• Use case: Store custom JSON data in a user object.
• URL: /users/<ID>/data
• Method: PUT
• JSON Payload:

  { <Custom JSON data> } 

• HTTP Response Status Codes:
  • 204: No content (successful)
  • 400: Bad request (invalid JSON payload)
  • 404: Not found (invalid User ID)

• Use case: Retrieve previously stored custom JSON data from a user object.
• URL: /users/<ID>/data
• Method: GET
• HTTP Response Status Codes:
  • 204: No content (successful)
  • 404: Not found (invalid User ID)
• HTTP Response Body:

  { <Custom JSON data> } 

• Use case: Checks if a supplied plain-text password matched the user's hashed password.
• URL: /users/<ID>/checkpw
• Method: POST
• JSON Payload:

  { "password": "<plain-text password>" } 

• HTTP Response Status Codes:
  • 200: OK (successful)
  • 400: Bad request (invalid JSON payload)
  • 404: Not found (invalid User ID)
• HTTP Response Body:

  { "result": true|false } 

Configuration is performed by setting the appropriate environment variables.