X-Road Example REST API

The X-Road Example REST API demonstrates an implementation of a REST API service that can be integrated into X-Road 7 as a service provider information system.

Table of Contents

• Software Requirements
• Certificate Generation
  • Server Certificate for HTTPS
  • Client Certificates for mTLS
    • Browser access using Self-Signed Client Certificate in mTLS setup
    • X-Road Security Server Certificate
    • Trusted Client Certificate Bundle
• Running the Application
  • Supported Profiles
  • Environment variables
  • Application URLs
  • Running Locally
  • Running with Docker

Software Requirements

• Java 21 or later
• Docker (optional)

Certificate Generation

Note

Certificate generation is only required for running the application with https or mtls profiles. If you're running with the default HTTP profile, you can skip this section.

The following examples generate certificates into certs folder at the project's root. If you'll change the location, ensure to update the paths in application configuration files or environment variables accordingly.

Server Certificate for HTTPS

Note

Accessing Swagger or OpenAPI specs in browser may cause a warning about the self-signed certificate. You can safely ignore it.

Generate a self-signed server certificate for HTTPS communication. This certificate is required for both https and mtls profiles.

openssl req -x509 -newkey rsa:4096 -days 365 -nodes \
-keyout ./certs/server-private-key.pem \
-out ./certs/server-certificate.pem \
-subj "/C=EE/O=Example/OU=Development/CN=localhost"

Client Certificates for mTLS

Mutual TLS (mTLS) enables client certificate authentication. It can be used for secure communication with X-Road Security Server. For more information, refer to X-Road Security Server User Guide -> Communication with Information Systems. The following steps will generate a self-signed client certificate to allow browser to access Swagger UI and Security Server to consume the service.

Important

• mTLS profile requires https profile in the list of active profiles.

Browser access using Self-Signed Client Certificate in mTLS setup

To access Swagger UI using your browser, generate a certificate and import it into your browser.

• Generate client certificate:

openssl req -x509 -newkey rsa:4096 -days 365 -nodes \
-keyout ./certs/client-private-key.pem \
-out ./certs/client-certificate.pem \
-subj "/C=EE/O=Example/OU=Development/CN=client.localhost"

• Generate PKCS12 file for browser import:

Note

You will be prompted to enter an export password. This password will be needed while importing the p12 file into your browser.

openssl pkcs12 -export -in certs/client-certificate.pem -inkey certs/client-private-key.pem -out certs/client-certificate.p12

• Import it into your browser by following your browser's official documentation on how to import certificates.

X-Road Security Server Certificate

When integrating with X-Road Security Server:

• Import the server-certificate.pem (generated above) to Security Server's trusted certificates
• Download the Security Server's certificate to include in your trusted clients certificate bundle

Note

The following steps assumes that the Security Server's certificate is named xroad-server-cert.pem

Trusted Client Certificate Bundle

This bundle will contain all trusted client certificates.

• Start with your browser certificate

cat certs/client-certificate.pem > certs/trusted-clients-bundle.pem

• Add X-Road Security Server certificate

cat certs/xroad-server-cert.pem >> certs/trusted-clients-bundle.pem

Tip

You can add more client certificates to the bundle anytime:

cat certs/another-client-cert.pem >> certs/trusted-clients-bundle.pem

---

Running the Application

Supported Profiles

The application supports three profiles:

• default (HTTP): No SSL/TLS - No certificate required
• https: Enables HTTPS with a self-signed server certificate - Requires server certificate for HTTPS. Use for encrypted communication.
• mtls: Enables mutual TLS (client certificate authentication) in addition to HTTPS - Requires server certificate for HTTPS + Client Certificates for mTLS. Use for secure, authenticated connections with X-Road Security Server.

Environment variables

Variable	Description	Mandatory	Example
SSL_CERTIFICATE	Path to server certificate file.	https and mtls	/certs/server-certificate.pem
SSL_CERTIFICATE_PRIVATE_KEY	Path to server private key file.	https and mtls	/certs/server-private-key.pem
CLIENT_CERTIFICATE	Path to trusted clients bundle.	mtls	/certs/trusted-clients-bundle.pem

Application URLs

Once the application is running, you can access the following endpoints based on the active profile:

Profile	Port	Swagger UI	OpenAPI Spec	Service URL
HTTP	8080	http://localhost:8080/swagger-ui/index.html	http://localhost:8080/v3/api-docs	http://localhost:8080/
HTTPS	8443	https://localhost:8443/swagger-ui/index.html	https://localhost:8443/v3/api-docs	https://localhost:8443/
mTLS	8443	https://localhost:8443/swagger-ui/index.html	https://localhost:8443/v3/api-docs	https://localhost:8443/

Running Locally

The fastest and easiest way to try out the application is by using the Spring Boot Gradle plugin.

Default (HTTP):

./gradlew bootRun

HTTPS:

SSL_CERTIFICATE=certs/server-certificate.pem \
  SSL_CERTIFICATE_PRIVATE_KEY=certs/server-private-key.pem \
  ./gradlew bootRun --args='--spring.profiles.active=https'

mTLS:

SSL_CERTIFICATE=certs/server-certificate.pem \
  SSL_CERTIFICATE_PRIVATE_KEY=certs/server-private-key.pem \
  CLIENT_CERTIFICATE=certs/trusted-clients-bundle.pem \
  ./gradlew bootRun --args='--spring.profiles.active=https,mtls'

---

Running with Docker

Build the Docker image:

docker build -t xrddev-example-restapi-dev .

Run with different profiles:

• Default (HTTP):

  docker run -d -p 8080:8080 xrddev-example-restapi-dev

• HTTPS:

  docker run -d -p 8443:8443 \
    -e SPRING_PROFILES_ACTIVE='https' \
    -e SSL_CERTIFICATE=/certs/server-certificate.pem \
    -e SSL_CERTIFICATE_PRIVATE_KEY=/certs/server-private-key.pem \
    -v $(pwd)/certs:/certs \
    xrddev-example-restapi-dev

• mTLS:

  docker run -d -p 8443:8443 \
    -e SPRING_PROFILES_ACTIVE='https,mtls' \
    -e SSL_CERTIFICATE=/certs/server-certificate.pem \
    -e SSL_CERTIFICATE_PRIVATE_KEY=/certs/server-private-key.pem \
    -e CLIENT_CERTIFICATE=/certs/trusted-clients-bundle.pem \
    -v $(pwd)/certs:/certs \
    xrddev-example-restapi-dev