Feature Wiki
Tabs
REST API: Authentication and Service Control (Phase 2)
Page Overview
[Hide]- 1 Initial Problem
- 2 Conceptual Summary
- 3 User Interface Modifications
- 4 Additional Information
- 4.1 Involved Authorities
- 4.2 Technical Aspects
- 4.3 Privacy
- 4.4 Security
- 4.5 Contact
- 4.6 Funding
- 5 Discussion
- 6 Implementation
- 6.1 Approval
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
ApiGatewaycomponent 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: Bearerheader. - 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
/pingstill 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.





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
- Authority to Sign off on Conceptual Changes: Hamouda, Ahmed [ahamouda]
- Authority to Sign off Code Changes: Hamouda, Ahmed [ahamouda]
- Authority to Curate Test Cases: Karki, Sagun [sagun]
- Assignee for Security Reports: Karki, Sagun [sagun]
- Assignee for Security Issues: Karki, Sagun [sagun]
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.
- `slim/slim`(^4.15.3) For HTTP request handling and routing.
- 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.
- For funding offers: Günther, Andre [ILIASBase].
- For technical inquiries: Hamouda, Ahmed [ahamouda].
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]