Feature Wiki

Information about planned and released features

Tabs

REST API: Authentication and Service Control (Phase 2)

1 Initial Problem

Phase 1 built the base of the ApiGateway component: the REST setup, the core structure, a first link to Activities, and the main API ideas. But Phase 1 has no login check (authentication) and no admin settings. Without these, the component is not safe to use on a live system. Users can’t safely create and manage their own API endpoints and activities, and the component can’t become part of the ILIAS core. So this phase adds authentication before the other phases.

This is a long project. We split it into phases so that each phase is stable and useful on its own. Plans for later phases may change based on community feedback.

  • Phase 1: Webservices API base (REST, core structure, first Activity link, main API ideas)
  • Phase 2: Security and access control (this page)
  • Phase 3: Swagger and middleware (OpenAPI documentation)
  • Phase 4: Input and output checks for Activities (OpenAPI documentation created automatically for all Activities)
  • Phase 5: SOAP webservice (add SOAP to the new ApiGateway component so that it can replace the current SOAP webservice over time)

2 Conceptual Summary

Phase 2 adds two things to the ApiGateway component:

Authentication

  • API requests use a token (a JWT), sent in the Authorization: Bearer header.
  • A client gets a token by sending an ILIAS username and password to POST /rest/auth/token. It gets back an access token and a refresh token.
  • The access token stays valid for a time the admin sets (default: 1 day).
  • When it expires, the client sends the refresh token to POST /rest/auth/refresh. This returns a new pair, and the old refresh token stops working.
  • The refresh token also expires (default: 7 days). After that, the user must log in again.
  • Endpoints that need a login reject requests without a valid token before any code runs. Public endpoints such as /ping still work without a token.

Admin settings

  • Admins can turn the REST webservice on or off.
  • Admins can set:
    • the secret key used to sign tokens (changing it logs out every user and app)
    • the signing algorithm and the hashing algorithm
    • how long access tokens and refresh tokens stay valid

3 User Interface Modifications

3.1 List of Affected Views

A new settings page in the admin dashboard to control each available webservice.

Click path: Administration > System Settings and Maintenance > Webservices

3.2 User Interface Details

New configuration page in the dashboard.

General Configurations
REST Configurations
Configuration help text
Allgemeine Konfigurationen
REST-Konfigurationen

3.3 New User Interface Concepts

We use kitchen-sink elements, so there are no foreseeable new user-interface modifications.

3.4 Accessibility Implications

No foreseeable accessibility modifications.

4 Additional Information

4.1 Involved Authorities

4.2 Technical Aspects

Missing Dependencies

  • Requires the following third-party libraries managed via Composer:
    • `slim/slim`(^4.15.3) For HTTP request handling and routing.
      • Purpose: provides routing, the middleware pipeline, and error handling. Used only inside the ApiGateway; other components never use Slim directly, so it can be replaced later.
      • Why Slim: small, mature, and built on PSR-7 and PSR-15, which ILIAS already uses. No templates, ORM, or container of its own.
      • License: MIT License, compatible with ILIAS (GPL-3.0).
      • Maintenance: actively maintained. Version 4.15.1 added official support for PHP 8.5. Slim 5 is in development; a later migration would only affect the ApiGateway.
      • Security: security issues are handled through published advisories and fixed quickly in patch releases. The minimum version 4.15.3 includes all current fixes.
      • Extra packages:nikic/fast-route (BSD-3-Clause, stable, last release 2018) and small PSR interface packages (MIT).
    • `psr/http-server-middleware` For middlewares.
  • Depends on the ILIAS core for bootstrapping and accessing global services, such as settings (`ilApiGatewaySettings`) and the user object from the DIC.

Existing Dependencies

  • Requires the following third-party libraries managed via Composer:
    • `firebase/php-jwt` For securely generating and validating JWT tokens to handle user authentication and sessions.
    • `guzzlehttp/psr7` For handling HTTP request and response bodies in a standardized way.
    • `psr/log` For the logger interface.

4.3 Privacy

The API will only provide a layer on top of the existing ILIAS components. There is no direct manipulation of the user data.

4.4 Security

As in the previous phase, adding new endpoints inherently increases the attack surface, introducing risks such as injection attacks, unauthorized access, and issues with token-based authentication. To mitigate these, users should embed security into the component's building blocks by:

  • Applying strict input validation and sanitization to prevent injection & related attacks.
  • Enforcing strict authorization checks on each new endpoint.
  • Using HTTPS to secure data in transit.
  • Conducting thorough security testing and audits to identify and resolve vulnerabilities before launch.

4.5 Contact

This feature is developed by Minervis GmbH.

4.6 Funding

  • If you are interested in funding this feature, please add your name and institution to this list.
  • HHU Düsseldorf - 6.000,00 € für Phase 2 - done!
  • Leibniz Universität Hannover (LUH)ZQS/E-Learning Service (ZQS/elsa) - OSDN - 19.360,00 € - done!
  • completed

5 Discussion

6 Implementation

The feature has been implemented by Hamouda, Ahmed [ahamouda].

6.1 Approval

Approved at {date} by {user}.

Last edited: 16. Nov 2026, 17:45, Hamouda, Ahmed [ahamouda]