# Advanced integration options

There are multiple flexible options for integrating your product with UDiTH Portal.

Code examples are available at:

<https://github.com/caxperts/upv-webservices-integration>

## Authentication

For specific use cases, it is possible to handle OpenID Connect authentication directly and use its wide range of options.

The BBV WebRTC integration package supports setting an access token directly without using the integrated automatic sign-in.
This is demonstrated in the login popup flow here:

<https://github.com/caxperts/upv-webservices-integration/tree/main/browserbasedviewing-api-samples/webrtc-integration-sample>

By calling `setAccessTokenCall`, you can pass the token directly. The original part of the sample relating to pop-ups and account handling is not required for this use case.
Please note that the token must be updated when it expires. The JWT token contains a lifetime property.

```typescript
token = 'eyJhbGciOiJSUzI1NiIsInR5cCI...'; // a valid OIDC access token

private connect() {
  this.upvApi = new UpvWebInterface(this.signalingServerBaseUrl + 'signaling');

  // Provide a function that returns the current access token
  this.upvApi.setAccessTokenCall(() => this.token);

  window.addEventListener(this.upvApi.connectedEvent, () => {
    // API now available
    let command = this.upvApi.createApiCommand("Select", null, null, "Task=Equipment", null, 1);
    this.upvApi.sendApiCommand(command, r => console.log('result', r));
  });

  this.upvApi.connect("http://demo.universalplantviewer.com/demoPlant/8/0", 'displayname', this.player.nativeElement);
}
```

> A complete, runnable version of this example is available in the [integration samples repository](https://github.com/caxperts/upv-webservices-integration/tree/main/browserbasedviewing-api-samples/webrtc-integration-sample).

By using this approach, it is possible to customise the product extensively.

### Example: Service accounts

By using Keycloak service accounts, it is possible to request authentication for a specific user without the regular user sign-in flow.
This is commonly used for machine-to-machine scenarios.

An access token can be obtained by using the standard OpenID Connect **Client Credentials Grant** flow.

### Access control

Clients that use the **Client Credentials Grant** automatically have a service account user created in Keycloak.
For example, for the client `example-client`, a user named `service-account-example-client` is created.

<img src="./media/UPVWebServices_advanced_accesscontrol.png" width="789" height="484">

After calling `ForceSynchronize` on the UDiTH Portal application side, this account is also available in the UDiTH Portal admin UI.
Here, you can configure the fine-grained access rights for the account.

<img src="./media/UPVWebServices_advanced_usermanagement.png" width="789" height="484">

The user group can then be assigned permissions for specific models.

<img src="./media/UPVWebServices_advanced_permission.png" width="789" height="484">

#### How to create a service account

- Open the Keycloak URL.
- Go to **Administration Console**.
- Sign in by using a Keycloak admin account. If you are not self-hosting the Keycloak server, contact your hosting provider and ask them to provide an admin account.
<img src="./media/service_account_1.png" width="789" height="484">
  - Make sure that your application realm is selected. The realm name is configurable during installation. The `master` realm must never be used. When using a hosting provider, this realm may be named differently.
  - Go to **Clients** in the left-hand menu. Service accounts are directly associated with an OpenID Connect client entry.

- Click **Create client**.
- Choose any value for **Client ID** and click **Next**.

<img src="./media/service_account_2.png" width="789" height="484">

- On the **Capability config** step, apply the following settings (shown in the image above):
  - **Client authentication**: **On**
  - **Authorization**: **Off**
  - **Authentication flow**: enable **Standard flow**, **Direct access grants**, and — most importantly — **Service accounts roles**.

  The **Service accounts roles** option is responsible for associating a new service account with the client and must be enabled for machine-to-machine authentication. You can, of course, change these settings if you have specific authentication requirements.
- Click **Next**.
- Leave **Login settings** unchanged and save the client.
- The client automatically receives a client secret, that is, a password. You can access it on the **Credentials** tab of the client.
- The generated Keycloak service account can be viewed on the client page under the **Service accounts roles** tab.