Graph Service Configuration

Introduction

The graph service provides the Graph API which is a RESTful web API used to access Infinite Scale resources. It is inspired by the Microsoft Graph API and can be used by clients or other services or extensions. Visit the Libre Graph API for a detailed specification of the API implemented by the graph service.

Default Values

  • Graph listens on port 9120 by default.

Restrict Username Patterns

Usernames can be restricted to follow certain patterns. Such patterns can be neccessary when using the internal IDM for example to align with local Unix username restrictions. Username restrictions can also be handled with an external IDM like Keycloak. The environment variable GRAPH_USERNAME_MATCH can be set to the following values to define where and how these restriction are handled:

  • none
    There is no internal username checking. Restrictions, if any, are defined in the external IDM like Keycloak.

  • default
    Usernames are restricted by the following criteria:

    • ASCII standard charset, no UTF-8

    • The username must start with either

      • an _ (underscore) or

      • a letter where there is no distinction between lower- and uppercase.

    • More characters from the ASCII charset including numbers, aligning to the Unix user namespace.

    • optionally an @ character followed by a domain name

Manual Filters

Using the API, you can manually filter like for users. See the Libre Graph API for examples in the developer documentation. Note that you can use and and or to refine results.

Sequence Diagram

The following image gives an overview of the scenario when a client requests to list available spaces the user has access to. To do so, the client is directed with his request automatically via the proxy service to the graph service.

mermaid graph

Users and Groups API

The graph service provides endpoints for querying users and groups. It features two different backend implementations:

  • ldap:
    This is currently the default backend. It queries user and group information from an LDAP server. Depending on the configuration, it can also be used to manage (create, update, delete) users and groups provided by an LDAP server.

  • cs3:
    This backend queries users and groups using the CS3 identity APIs as implemented by the users and groups service. This backend is currently still experimental and only implements a subset of the Libre Graph API. It should not be used in production.

LDAP Configuration

The LDAP backend is configured using a set of environment variables. A detailed list of all the available configuration options can be found in the configuration section below. The LDAP related options are prefixed with OCIS_LDAP_ (or GRAPH_LDAP_ for settings specific to the graph service).

Read-Only Access to Existing LDAP Servers

To connect the graph service to an existing LDAP server, set OCIS_LDAP_SERVER_WRITE_ENABLED to false to prevent the graph service from sending write operations to the LDAP server. Also set the various OCIS_LDAP_* environment variables to match the configuration of the LDAP server you are connecting to. An example configuration for connecting Infinite Scale to an instance of Microsoft Active Directory is available here.

Using a Write Enabled LDAP Server

To use the graph service for managing (create, update, delete) users and groups, a write enabled LDAP server is required. In the default configuration, the graph service will use the simple LDAP server that is bundled with infinite Scale in the idm service which provides all the required features. It is also possible to setup up an external LDAP server with write access for use with Infinite Scale. It is recommended to use OpenLDAP for this. The LDAP server needs to fulfill a couple of requirements with respect to the available schema:

  • The LDAP server must provide the inetOrgPerson object class for users and the groupOfNames object class for groups.

  • The graph service maintains a few additional attributes for users and groups that are not available in the standard LDAP schema. A schema file (ldif), ready to use with OpenLDAP defining those additional attributes, is available: here.

Query Filters Provided by the Graph API

Some API endpoints provided by the graph service allow query filters to be specified. The filter syntax is based on the OData Specification. See the Libre Graph API for examples on the filters supported when querying users.

Keycloak Configuration for the Personal Data Export

If Keycloak is used for authentication, GDPR regulations require to add all personal identifiable information that Keycloak has about the user to the personal data export. To do this, the following environment variables must be set:

Environment Variable Description

OCIS_KEYCLOAK_BASE_PATH

The URL to the Keycloak instance.

OCIS_KEYCLOAK_CLIENT_ID

The client ID of the client that is used to authenticate with Keycloak. This client has to be able to list users and get the credential data.

OCIS_KEYCLOAK_CLIENT_SECRET

The client secret of the client that is used to authenticate with Keycloak.

OCIS_KEYCLOAK_CLIENT_REALM

The realm the client is defined in.

OCIS_KEYCLOAK_USER_REALM

The realm Infinite Scale users are defined in.

OCIS_KEYCLOAK_INSECURE_SKIP_VERIFY

If set to true, the TLS certificate of the Keycloak instance is not verified.

Keycloak Client Configuration

The client that is used to authenticate with Keycloak has to be able to list users and get the credential data. To do this, the following roles have to be assigned to the client and they have to be about the realm that contains the Infinite Scale users:

  • view-users

  • view-identity-providers

  • view-realm

  • view-clients

  • view-events

  • view-authorization

Note that these roles are only available to assign if the client is in the master realm.

Translations

The graph service has embedded translations sourced via transifex to provide a basic set of translated languages. These embedded translations are available for all deployment scenarios. In addition, the service supports custom translations, though it is currently not possible to just add custom translations to embedded ones. If custom translations are configured, the embedded ones are not used. To configure custom translations, the GRAPH_TRANSLATION_PATH environment variable needs to point to a base folder that will contain the translation files. This path must be available from all instances of the userlog service, a shared storage is recommended. Translation files must be of type .po or .mo. For each language, the filename needs to be graph.po (or graph.mo) and stored in a folder structure defining the language code. In general the path/name pattern for a translation file needs to be:

{GRAPH_TRANSLATION_PATH}/{language-code}/LC_MESSAGES/graph.po

The language code pattern is composed of language[_territory] where language is the base language and _territory is optional and defines a country.

For example, for the language de, one needs to place the corresponding translation files to

{GRAPH_TRANSLATION_PATH}/de/LC_MESSAGES/graph.po


For the time being, the embedded ownCloud Web frontend only supports the main language code but does not handle any territory. When strings are available in the language code language_territory, the web frontend does not see it as it only requests language. In consequence, any translations made must exist in the requested language to avoid a fallback to the default.

Translation Rules

  • If a requested language code is not available, the service tries to fall back to the base language if available. For example, if the requested language-code de_DE is not available, the service tries to fall back to translations in the de folder.

  • If the base language de is also not available, the service falls back to the system’s default English (en), which is the source of the texts provided by the code.

Default Language

The default language can be defined via the OCIS_DEFAULT_LANGUAGE environment variable. See the settings service for a detailed description.

Caching

The graph service can use a configured store via the global OCIS_CACHE_STORE environment variable.

Note that for each global environment variable, an independent service-based one might be available additionally. For precedences see Environment Variable Notes. Check the configuration section below. Supported stores are:

Store Type Description

memory

Basic in-memory store. Will not survive a restart.
Usually the default for caches. See the store environment variable for which one is used.

nats-js-kv

Stores data using key-value-store feature of NATS JetStream.
Usually the default for stores, see the store environment variable for which one is used.

redis-sentinel

Stores data in a configured Redis Sentinel cluster.

noop

Stores nothing. Useful for testing. Not recommended in production environments.
The graph service can only be scaled if not using the memory store and the stores are configured identically over all instances!
If you have used one of the deprecated stores of a former version, you should reconfigure to use one of the supported ones as the deprecated stores will be removed in a later version.
Store specific notes

  • When using redis-sentinel:
    The Redis master to use is configured via e.g. OCIS_CACHE_STORE_NODES in the form of <sentinel-host>:<sentinel-port>/<redis-master> like 10.10.0.200:26379/mymaster.

  • When using nats-js-kv:

    • It is recommended to set OCIS_CACHE_STORE_NODES to the same value as OCIS_EVENTS_ENDPOINT. That way the cache uses the same nats instance as the event bus. See the Event Bus Configuration for more details.

    • Authentication can be added, if configured, via OCIS_CACHE_AUTH_USERNAME and OCIS_CACHE_AUTH_PASSWORD.

    • It is possible to set OCIS_CACHE_DISABLE_PERSISTENCE to instruct nats to not persist cache data on disc.

Event Bus Configuration

The Infinite Scale event bus can be configured by a set of environment variables.

  • In case of an orchestrated installation like with Docker or Kubernetes, the event bus must be an external service for scalability like a Redis Sentinel cluster or a key-value-store NATS JetStream. Both named stores are supported and also used in Caching and Persistence. The store used is not part of the Infinite Scale installation and must be separately provided and configured.

  • Note that from a configuration point of view, caching and persistence are independent of the event bus configuration.

Note that for each global environment variable, a service-based one might be available additionally. For precedences see Environment Variable Notes. Check the configuration section below.

Without the aim of completeness, see the list of environment variables to configure the event bus:

Envvar Description

OCIS_EVENTS_ENDPOINT

The address of the event system.

OCIS_EVENTS_CLUSTER

The clusterID of the event system. Mandatory when using NATS as event system.

OCIS_EVENTS_ENABLE_TLS

Enable TLS for the connection to the events broker.

OCIS_INSECURE

Whether to verify the server TLS certificates.

OCIS_EVENTS_AUTH_USERNAME

The username to authenticate with the events broker.

OCIS_EVENTS_AUTH_PASSWORD

The password to authenticate with the events broker.

Configuration

Environment Variables

The graph service is configured via the following environment variables. Read the Environment Variable Types documentation for important details. Column IV shows with which release the environment variable has been introduced.

404: Not Found

  • 8.2.0

404: Not Found

YAML Example

  • 8.2.0

404: Not Found