Shield

Shield is a simple authentication service built with java. It provides a simple REST API for ease.

Getting Started

before you can use shield, be sure to read the documentation.

Docker

Run shield in container

sudo docker run -p 8080:8080 -d kasutu/shield

Java Maven

Run this project after cloning using mvn

mvn spring-boot:run

if you havnt installed maven, Install maven now

---

Payloads

Example using fetch in node

const BASE_URL = 'http://localhost:8080';
const ENDPOINT = '/api/v1/register';

const data = {
  username: 'admin',
  password: 'admin',
};

const response = await fetch(BASE_URL + ENDPOINT, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
});

It is important to note that the BASE_URL will be different from the example.

Variations

const BASE_URL = 'http://localhost';
const BASE_URL = 'http://splitscale.systems:8080';
const BASE_URL = 'http://splitscale.systems';

take note that 8080 is the port number

Endpoints

Registration

This method returns the id of the user that has been registered.

POST BASE_URL/api/v1/register

Request body

{
  "username": "admin",
  "password": "admin"
}

Response body

"fc4ef5de-6411-4e8f-bc8b-c95297015a0b"

Login

This method returns a ShieldUser on successful login.

POST BASE_URL/api/v1/login

Request body

{
  "username": "admin",
  "password": "admin"
}

Response header

The header includes a token key that contains a valid JWT string

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJDYW5kYWNlIiwiZXhwIjoxNjg1MTgxMzMzLCJuYmYiOjE2ODUxODA0MzMsImlhdCI6MTY4NTE4MDQzMywiYXVkIjoiOTNiM2ZiMzgtZWIwNS00OGM4LTg5MGMtNmI0MDY0ZGEyMTljIiwianRpIjoiSldULWQzNjZmMTYzLTM2NjktNDJiMy04ZTYzLTM1YzJhMGEzMTA5YyJ9.tHqLC1oUf_EEtKP2zA6RXLL_WKFG_wRtILSTu6aMFe4"
}

Response body

{
  "id": "93b3fb38-eb05-48c8-890c-6b4064da219c",
  "created": "2023-05-27T09:40:33.000+00:00",
  "edited": "2023-05-27T09:40:33.000+00:00",
  "displayName": "joejoe",
  "firstName": "joe",
  "lastName": "daboss",
  "photoUrl": "https://api.dicebear.com/6.x/notionists/svg?seed=Harley",
  "email": "joedaboss@gmail.com"
}

ValidateJwt

This method returns a token and the parsed jwt claims.
TODO: change the returned claims to custom claims in the future

POST BASE_URL/api/v1/validateJwt

Request body

{
  "jwtToken": "eyJhbGciOiJIUzI1NiJ9...",
  "userId": "93b3fb38-eb05-48c8-890c-6b4064da219c"
}

Response body

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJDYW5kYWNlIiwiZXhwIjoxNjg1MTgxMzMzLCJuYmYiOjE2ODUxODA0MzMsImlhdCI6MTY4NTE4MDQzMywiYXVkIjoiOTNiM2ZiMzgtZWIwNS00OGM4LTg5MGMtNmI0MDY0ZGEyMTljIiwianRpIjoiSldULWQzNjZmMTYzLTM2NjktNDJiMy04ZTYzLTM1YzJhMGEzMTA5YyJ9.tHqLC1oUf_EEtKP2zA6RXLL_WKFG_wRtILSTu6aMFe4",
  "claims": {
    "iss": "Candace",
    "exp": 1685181333,
    "nbf": 1685180433,
    "iat": 1685180433,
    "aud": "93b3fb38-eb05-48c8-890c-6b4064da219c",
    "jti": "JWT-d366f163-3669-42b3-8e63-35c2a0a3109c"
  }
}

invalidateJwt

This method returns a string token.

POST BASE_URL/api/v1/inValidateJwt

Request body

// valid token
{
  "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJDYW5kYWNlIiwiZXhwIjoxNjg1MTgxMzMzLCJuYmYiOjE2ODUxODA0MzMsImlhdCI6MTY4NTE4MDQzMywiYXVkIjoiOTNiM2ZiMzgtZWIwNS00OGM4LTg5MGMtNmI0MDY0ZGEyMTljIiwianRpIjoiSldULWQzNjZmMTYzLTM2NjktNDJiMy04ZTYzLTM1YzJhMGEzMTA5YyJ9.tHqLC1oUf_EEtKP2zA6RXLL_WKFG_wRtILSTu6aMFe4"
}

Response body

// invalid token
{
  "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJDYW5kYWNlIiwiZXhwIjoxNjg1MTgwNDM0LCJuYmYiOjE2ODUxODA0MzQsImlhdCI6MTY4NTE4MDQzNCwiYXVkIjoiOTNiM2ZiMzgtZWIwNS00OGM4LTg5MGMtNmI0MDY0ZGEyMTljIiwianRpIjoiSldULWQzNjZmMTYzLTM2NjktNDJiMy04ZTYzLTM1YzJhMGEzMTA5YyJ9.OVCMcXquRxVME92gcn_a1jl6GlLTHD1EQMHjY9RxQ5I"
}

Implement in next auth

NextAuth.js Custom provider guide