Documentation of the client core and framework libraries, as usable for custom client development.

Introduction

Spawned from the development of the yuuvis® Momentum reference client, we offer two libraries, which may be used when developing a custom client application in Angular.

• The client core library provides a set of services to interact with a yuuvis® Momentum backend.
  
• The client framework library provides yuuvis developers with a collection of UI components, like hit lists, for creating their own client applications.

Both libraries have their own documentation page, as linked below.

Client Core Libraries Documentation

You reach the documentation depicted below via https://yuuvis-cc.yuuvis.org/.  Notice the drop-down for switching between both documentations.

A core and a framework library  with components including documentation are publically available here:

• This is the entry point for creating a new client project: https://www.npmjs.com/package/@yuuvis/project
• The core library is available here: https://www.npmjs.com/package/@yuuvis/core
• The framework library is available here: https://www.npmjs.com/package/@yuuvis/framework
• A demo-client project is available here: https://github.com/OPTIMALSYSTEMS/yuuvis-demo-schematics-project 
• The reference client sources are available here: https://github.com/OPTIMALSYSTEMS/yuuvis-client

A short introduction is given here:

Running Clients outside the yuuvis® Momentum cluster

By default, client applications built with @yuuvis/core library are supposed to be deployed inside the yuuvis® Momentum cluster. As a main advantage, there is no responsibility for the library to handle the authentication process. Users authenticate directly via the AUTHENTICATION service.

As of yuuvis® Momentum version 2021 Autumn, the @yuuvis/core library allows for the built of clients that can be deployed outside the yuuvis® Momentum cluster. Such clients authenticate via OpenID Connect to the AUTHENTICATION service and can thus be hosted fully independently. They can even be configured to support switching between different yuuvis® Momentum clusters. Users select the cluster to which they want to connect.

An example project is provided on GitHub.

The following configuration steps are required to allow for the client deployment outside a yuuvis® Momentum cluster.

Setup Keycloak

Configure a Client inside your Keycloak Realm that will be used to trigger login.

Client ID: 'spa-client' // choose your own name
Client Protocol: 'openid-connect'
Access Type: 'public'
Valid Redirect URIs: // match your environment
Web Origins: '+' // means: everything that's also invalid redirect uris

Advanced Settings
Proof Key for Code Exchange Code Challenge Method: 'S256'

Setup Project

Choose one of the following ways to setup your project.

Setup via 'oidc.json' Configuration File

Create a file oidc.json with the following content in the root directory of your assets folder.

// ./src/assets/oidc.json
{
  "host": "https://kolibri.enaioci.net",  // yuuvis backend URI
  "tenant": "kolibri",  // yuuvis tenant (equals Keycloak realm)
  "issuer": "https://auth.enaioci.net/auth/realms/kolibri",
  "clientId": "spa-client",
}

Setup via Module Configuration

During the import of YuvCoreModule, specify the following configuration.

// app.module.ts

imports: [
    YuvCoreModule.forRoot({
      // ... other config values
      oidc: {
        host: "https://kolibri.enaioci.net",
        tenant: "kolibri",
        issuer: "https://auth.enaioci.net/auth/realms/kolibri",
        clientId: "spa-client",
      }
    })
  ],

Setup via Dynamic Initialization

In case you do not know about the OIDC properties when your application starts (the OIDC profile needs to be loaded or users select one of several profiles), you will just import YuvCoreModule without OIDC config. The @yuuvis/core library will try the default initialization as if the client were deployed within a yuuvis® Momentum cluster. This will cause some console errors which can be ignored.

Once you are ready to specify the OIDC configuration, you can re-trigger the initialization of the library's core module:

export class AppComponent {
  constructor(@Inject(CORE_CONFIG) private coreConfig: CoreConfig, private coreInit: CoreInit) {}

  login(target: OpenIdConfig) {
    this.coreConfig.oidc = {
      host: 'https://kolibri.enaioci.net',
      tenant: 'kolibri',
      issuer: 'https://auth.enaioci.net/auth/realms/kolibri',
      clientId: 'spa-client'
    };
    this.coreInit.initialize();
  }
}

Summary

You have been pointed to the yuuvis® Momentum client libraries, which facilitate the rapid development of your own custom client application in Angular.