PHPackages                             edu-sharing/auth-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. edu-sharing/auth-plugin

ActiveLibrary[Authentication & Authorization](/categories/authentication)

edu-sharing/auth-plugin
=======================

Plugin to provide authentification via Auth By App with a edu-sharing repository

10.0.2(1mo ago)116.2k—3.4%GPL-3.0-onlyPHPPHP >= 8.3

Since May 23Pushed 1w ago3 watchersCompare

[ Source](https://github.com/edu-sharing/php-auth-plugin)[ Packagist](https://packagist.org/packages/edu-sharing/auth-plugin)[ RSS](/packages/edu-sharing-auth-plugin/feed)WikiDiscussions 10.0 Synced yesterday

READMEChangelogDependencies (2)Versions (6)Used By (0)

Edu-sharing PHP Library
=======================

[](#edu-sharing-php-library)

Usage Scenarios
---------------

[](#usage-scenarios)

This library is intended for third party systems (e.g., LMS, CMS) to interconnect with edu-sharing to embed edu-sharing materials into their pages.

Examples
--------

[](#examples)

This repository includes a minimal example for using the library. For a more involved example, please check out the Edu-Sharing Moodle Plugins:

- [Activity Plugin](https://github.com/edu-sharing/moodle-mod_edusharing) wraps this library to facilitate communication with the repository (class EdusharingService)
- [Tiny MCE Plugin](https://github.com/edu-sharing/moodle-tiny_edusharing) handles embedding Edu-Sharing objects in a wysiwyg editor.
- [Filter Plugin](https://github.com/edu-sharing/moodle-filter_edusharing) handles displaying embedded ES-Objects.

### Run example

[](#run-example)

Call

```
docker compose build && docker compose up
```

and open in your browser:

In your storage, check the new folder `data`. There you'll find the `sample-app.properties.xml` file you must upload to your repository (see Pre-Requisites).

Pre-Requisites
--------------

[](#pre-requisites)

Every third-party system will need to be registered in edu-sharing first. edu-sharing 9.0 or greater must be used to make use of this library.

To register systems, log in to your edu-sharing as an administrator, switch to Admin-Tools → Remote-Systems

When using Edu-Sharing >10.0 with the new rendering service, you need to add your local testing host to the list of allowed hosts:

1. Login to Edu-Sharing as admin
2. Admin-Tools
3. Advanced System Configuration
4. homeApplication.properties.xml edit
5. Scroll to "allow\_origin" and add your local host (e.g., , more than one allowed as a comma-separated list)
6. Apply
7. Wait for the changes to take effect (a job runs every 5 minutes to sync allowed origins with the rendering service)

This step is not required in production systems.

Composer Usage (Beta)
---------------------

[](#composer-usage-beta)

If you already use composer, you can fetch this library as a composer dependency

`composer require edu-sharing/auth-plugin 10.0.x-dev`.

You can access all classes in the `EduSharing` namespace.

Find out more about the package and available versions here:

How to Register Your App?
-------------------------

[](#how-to-register-your-app)

The registration is handled by providing a public key to the repository (via an XML file).

You can create such a registration file by calling `php example/example.php`. It will create a `private.key` file (make sure to safely store this file and never expose it to clients!). The generated `properties.xml` file can then be used to register the app in edu-sharing. (see [Pre-Requisites](#pre-requisites)) (This is not required when using docker, it will be executed automatically)

Basic Workflows & Features
------------------------------

[](#basic-workflows--features)

There are two common use cases:

### 1. Logging in and selecting an object to embed

[](#1-logging-in-and-selecting-an-object-to-embed)

For this workflow, you first need to call `getTicketForUser` including the `userid` to fetch a ticket for your authenticated user. Since your app is registered via the public key, we will trust your request and return you a ticket (similar to a user session).

After you have a ticket, you will navigate the user to the edu-sharing UI so that they can select an element. `/components/search?ticket=&reurl=IFRAME`

When the user has picked an element, you will receive the particular element via JavaScript:

```
window.addEventListener('message', receiveMessage, false);
function receiveMessage(event) {
    if (event.data.event === 'APPLY_NODE') {
        console.log(event.data.data);
    }
}
```

You now need to use the method `createUsage` in order to create a persistent usage for this element.

Persist the data you receive from this method to display it later.

A full working example is given in `example/index.html` (you need to register your app first, see above)

Check the `docker-compose.yml` file for the `BASE_URL` variables. Then use `docker compose build && docker compose up -d` inside the `example` folder and open .

### 2. Rendering / displaying a previously embedded object

[](#2-rendering--displaying-a-previously-embedded-object)

If you previously generated a usage for an object, you can fetch it for displaying / rendering. Simply call `getNodeByUsage` including the usage data you received previously.

You'll get the full node object (see the REST specification) as well as a ready-to-embed HTML snipped (`detailsSnippet`).

#### 2.1 Rendering / displaying with Edu-Sharing 10.0

[](#21-rendering--displaying-with-edu-sharing-100)

**UPDATE FOR EDU-SHARING 10.0**Edusharing 10.0 uses a new Rendering Service which no longer provides a raw HTML snippet for embedding. Instead, it makes use of a web component for displaying the content.

##### 2.1.1 Configuring the Edu-Sharing REST base url

[](#211-configuring-the-edu-sharing-rest-base-url)

The web component calls two public endpoints of the Edu-Sharing REST API for which it needs the base path. Please configure it thus:

```
window.__env = {
    EDU_SHARING_API_URL: YOUR_REPO_HOST/edu-sharing + '/rest'
};

```

##### 2.1.2 Adding the web component to your app

[](#212-adding-the-web-component-to-your-app)

You can either add the web component to your app by using npm ([Link](https://www.npmjs.com/package/ngx-edu-sharing-rendering-web-component)) or by using the assets provided by the repository. The latter option is recommended as it ensures smooth updates and is used in the following examples. In any case two assets need to be added: `main.js` and `styles.css`:

```
const script = document.createElement('script');
script.src = 'YOUR_REPO_HOST/edu-sharing/web-components/rendering-service/main.js';
script.type = 'module';
document.head.appendChild(script);

const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = 'YOUR_REPO_HOST/edu-sharing/web-components/rendering-service/styles.css';
link.type = 'text/css';
document.head.appendChild(link);

```

or

```

```

By default, the web component is bundled using ESM. If you need AMD (for example for apps using require.js) simply change `rendering-service` to `rendering-service-amd` in the links.

**NOTE**: When using the AMD bundle, you need to tell webpack where to look for assets and chunks:

```
window.__EDUSHARING_PUBLIC_PATH__ = `${repoUrl}/web-components/rendering-service-amd/`;

```

##### 2.1.3 Enabling the service worker

[](#213-enabling-the-service-worker)

For session handling, the new rendering Service uses a cookie. If, for some reason, the cookie is rejected by the browser, an authentication header is managed and set by a service worker as a backup strategy. You need to add this service worker to your app. As it has to be served by your app using specific headers, you have to create your own endpoint:

```
header('Content-Type: text/javascript');
header('Service-Worker-Allowed: /');
header('Cache-Control: no-cache, no-store, must-revalidate');

```

For an example endpoint see: [Moodle Service Worker Endpoint](https://github.com/edu-sharing/moodle-filter_edusharing/blob/main/getServiceWorker.php)As with the web component itself you can either use the npm package and serve the "edu-service-worker.js" from the node modules folder or create a proxy for the service worker hosted by the repository (either `YOUR_REPO_HOST/edu-sharing/web-components/rendering-service/edu-service-worker.js` or `YOUR_REPO_HOST/edu-sharing/web-components/rendering-service-amd/edu-service-worker.js`)

With the endpoint/proxy in place, you can now add the service worker like this

```
const serviceWorkerScript = `PATH/TO/YOUR/SERVICEWORKERENDPOINT/getServiceWorker.php`;
if ('serviceWorker' in navigator && !navigator.serviceWorker.ready) {
    await navigator.serviceWorker.register(serviceWorkerScript, {
        scope: '/'
    });
    await navigator.serviceWorker.ready;
}
```

**Important:**If, for some reason, you use a proxy for communication with the Rendering Service 2 API, please make sure it also forwards the "Authentication-Info" header. It is necessary for the service worker to function.

**NOTE:**When testing locally (using non-secure http), you need to allow service workers in your browser:

- Chrome: chrome://flags → Insecure origins treated as secure → Add your origin (e.g., ) → Enable
- Firefox: dev console → Settings → Check "Enable service workers over http (when toolbox is open)"

##### 2.1.4 Signature algorithm handling

[](#214-signature-algorithm-handling)

The Edu-Sharing dev team currently migrates the repository service to current security standards. To ensure a secure encryption algorithm is used in your plugin, the library determines the signature algorithm through a `SignatureHandler`.

By default the library already uses the built-in `DefaultSignatureHandler`. It reads the algorithm advertised by the connected repository from its `_about` endpoint and falls back to the base default algorithm (`SHA1withRSA`) if the repository does not provide one — so for most integrations no further setup is required.

**Recommended:** Because `getAlgorithm()` is called on every signed request, the `DefaultSignatureHandler` would otherwise hit the repository's About API each time. To avoid this, extend `DefaultSignatureHandler` and persist the resolved algorithm in a global storage or your host system's session, so the repository is only queried once per session:

```