Home Page

REST Services Documentation

Welcome to the documentation for interacting with RESTful web services. This guide explains how to use various tools to make requests and includes a section on handling authentication if security is enabled.

Note for Beginners: If you are new to web services, each section includes basic examples using curl and Burp Suite. These examples will help you learn how to send requests and handle authentication when required.

Available Services

WS Echo Service - A service to echo back messages sent to it, useful for testing connectivity.
WS DNS Lookup Service - Perform DNS lookups by providing a hostname.
WS Test Connectivity Service - Verify the connection to the web service.
WS User Account Service - Manage user accounts with CRUD operations (Create, Read, Update, Delete).
WS Login Service - Authenticate clients and receive a JWT for further requests.

Understanding Security Levels and Authentication

This system has multiple security levels that affect access to the web services:

Security Level 0 - No authentication required. You can send requests without any additional headers or tokens.
Security Level 1 or Higher - Authentication with a JWT token is required for all services except ws-login. You must obtain a JWT token by logging in through the ws-login endpoint using your client_id and client_secret.

Important: At security level 1 or higher, you must include a JWT token in the Authorization header for each request. Without a valid token, you will receive a 401 Unauthorized error.

Step-by-Step Guide to Using JWT Authentication

Log In to Obtain a JWT Token: Send a POST request to the WS Login Service using your client_id and client_secret to authenticate. If successful, the response will include a JWT token.
Example (curl):
```
curl -X POST http://mutillidae.localhost/webservices/rest/ws-login.php \
-d "client_id=your-client-id&client_secret=your-client-secret"
```
The response will include a token in the format:
```
{"token": "your-jwt-token-here"}
```
Save the Token: Copy the JWT token from the response and store it securely. You will need to include it in the Authorization header of each authenticated request.
Include the Token in Requests: When calling any authenticated endpoint, include the token in the Authorization header using the format Bearer <your-token>.

Examples of Making Authenticated Requests

Using curl

Below is an example of an authenticated request using curl:

curl -X GET http://mutillidae.localhost/webservices/rest/ws-dns-lookup.php?hostname=google.com \ 
-H "Authorization: Bearer <your-token>"

Using Burp Suite

To send an authenticated request in Burp Suite:

Open Burp Suite and navigate to the Repeater tab.

Enter the URL in the Request line, such as:

GET /webservices/rest/ws-dns-lookup.php?hostname=google.com HTTP/1.1
Host: mutillidae.localhost

In the Headers section, add an Authorization header:
```
Authorization: Bearer your-jwt-token-here
```
Click Send to submit the request. If the token is valid, you will receive a successful response from the server.

How to Use the Services

Each service page provides:

An overview of the service functionality.
Examples of requests using Burp Repeater and curl.
Details about the expected response from the service.
Troubleshooting tips in case of issues.

Troubleshooting Common Issues

Ensure the web server is running and accessible on mutillidae.localhost.
Verify the correct HTTP method (GET, POST, etc.) is used for each service.
If using Burp Suite, confirm that traffic is correctly routed to the web service.
If receiving a 401 Unauthorized error, ensure your token is included in the Authorization header and has not expired.

If you have any further questions or need assistance, feel free to reach out to your instructor or class support team.