Graph Service Configuration
Introduction
The Infinite Scale Graph service provides a simple graph world API which can be used by clients or other services or extensions.
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.
Caching
The graph
service can use a configured store via GRAPH_CACHE_STORE
. Possible stores are:
Store Type | Description |
---|---|
|
Basic in-memory store and the default. |
|
Advanced in-memory store allowing max size. |
|
Stores data in a configured Redis cluster. |
|
Stores data in a configured Redis Sentinel cluster. |
|
Stores data in a configured etcd cluster. |
|
Stores data using the key-value-store feature of NATS JetStream. |
|
Stores nothing. Useful for testing. Not recommended in production environments. |
-
Note that in-memory stores are by nature not reboot-persistent.
-
Though usually not necessary, a database name and a database table can be configured for event stores if the event store supports this. Generally not applicable for stores of type
in-memory
. These settings are blank by default which means that the standard settings of the configured store apply. -
The graph service can be scaled if not using
in-memory
stores and the stores are configured identically over all instances. -
When using
redis-sentinel
, the Redis master to use is configured viaGRAPH_CACHE_STORE_NODES
in the form of<sentinel-host>:<sentinel-port>/<redis-master>
like10.10.0.200:26379/mymaster
.
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 |
---|---|
|
The URL to the Keycloak instance. |
|
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. |
|
The client secret of the client that is used to authenticate with Keycloak. |
|
The realm the client is defined in. |
|
The realm Infinite Scale users are defined in. |
|
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.
Configuration
Environment Variables
The graph
service is configured via the following environment variables. Read the Environment Variable Types documentation for important details.
Deprecation Info | Deprecation Version | Removal Version | Deprecation Replacement |
---|---|---|---|
LDAP_BIND_PASSWORD changing name for consistency |
4.0.2 |
5.0.0 |
OCIS_LDAP_BIND_PASSWORD |
Name | Type | Default Value | Description |
---|---|---|---|
|
bool |
false |
Activates tracing. |
|
string |
|
The type of tracing. Defaults to '', which is the same as 'jaeger'. Allowed tracing types are 'jaeger' and '' as of now. |
|
string |
|
The endpoint of the tracing agent. |
|
string |
|
The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset. |
|
string |
|
The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'. |
|
bool |
false |
Activates pretty log output. |
|
bool |
false |
Activates colorized log output. |
|
string |
|
The path to the log file. Activates logging to this file if set. |
|
string |
memory |
The type of the cache store. Supported values are: 'memory', 'ocmem', 'etcd', 'redis', 'redis-sentinel', 'nats-js', 'noop'. See the text description for details. |
|
[]string |
[] |
A comma separated list of nodes to access the configured store. This has no effect when 'memory' or 'ocmem' stores are configured. Note that the behaviour how nodes are used is dependent on the library of the configured store. |
|
string |
ocis |
The database name the configured store should use. |
|
string |
roles |
The database table the store should use. |
|
Duration |
336h0m0s |
Time to live for cache records in the graph. The duration can be set as number followed by a unit identifier like s, m or h. Defaults to '336h' (2 weeks). |
|
int |
0 |
The maximum quantity of items in the store. Only applies when store type 'ocmem' is configured. Defaults to 512. |
|
string |
127.0.0.1:9124 |
Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed. |
|
string |
|
Token to secure the metrics endpoint. |
|
bool |
false |
Enables pprof, which can be used for profiling. |
|
bool |
false |
Enables zpages, which can be used for collecting and viewing in-memory traces. |
|
string |
127.0.0.1:9120 |
The bind address of the HTTP service. |
|
string |
/graph |
Subdirectory that serves as the root for this HTTP service. |
|
bool |
false |
Activates TLS for the http based services using the server certifcate and key configured via OCIS_HTTP_TLS_CERTIFICATE and OCIS_HTTP_TLS_KEY. If OCIS_HTTP_TLS_CERTIFICATE is not set a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true. |
|
string |
|
Path/File name of the TLS server certificate (in PEM format) for the http services. |
|
string |
|
Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services. |
|
string |
|
An optional API bearer token |
|
[]string |
[*] |
A comma-separated list of allowed CORS origins. See following chapter for more details: Access-Control-Allow-Origin at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin |
|
[]string |
[GET POST PUT PATCH DELETE OPTIONS] |
A comma-separated list of allowed CORS methods. See following chapter for more details: Access-Control-Request-Method at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method |
|
[]string |
[Authorization Origin Content-Type Accept X-Requested-With X-Request-Id Purge Restore] |
A blank or comma-separated list of allowed CORS headers. See following chapter for more details: Access-Control-Request-Headers at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers. |
|
bool |
true |
Allow credentials for CORS.See following chapter for more details: Access-Control-Allow-Credentials at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials. |
|
int |
20 |
The amount of group members allowed to be added with a single patch request. |
|
string |
default |
Apply restrictions to usernames. Supported values are 'default' and 'none'. When set to 'default', user names must not start with a number and are restricted to ASCII characters. When set to 'none', no restrictions are applied. The default value is 'default'. |
|
bool |
true |
Whether to assign newly created users the default role 'User'. Set this to 'false' if you want to assign roles manually, or if the role assignment should happen at first login. Set this to 'true' (the default) to assign the role 'User' when creating a new user. |
|
string |
com.owncloud.api.gateway |
The CS3 gateway endpoint. |
|
string |
|
TLS mode for grpc connection to the go-micro based grpc services. Possible values are 'off', 'insecure' and 'on'. 'off': disables transport security for the clients. 'insecure' allows using transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). 'on' enables transport security, including server certificate verification. |
|
string |
|
Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the go-micro based grpc services. |
|
string |
|
The secret to mint and validate jwt tokens. |
|
string |
|
The ocis application ID shown in the graph. All app roles are tied to this ID. |
|
string |
ownCloud Infinite Scale |
The oCIS application name |
|
string |
https://localhost:9200 |
The public facing URL of WebDAV. |
|
string |
/dav/spaces/ |
The WebDAV subpath for spaces. |
|
string |
1000000000 |
The default quota in bytes. |
|
int |
60000000000 |
Max TTL in seconds for the spaces property cache. |
|
int |
60000000000 |
Max TTL in seconds for the spaces users cache. |
|
int |
60000000000 |
Max TTL in seconds for the spaces groups cache. |
|
string |
ldap |
The user identity backend to use. Supported backend types are 'ldap' and 'cs3'. |
|
string |
ldaps://localhost:9235 |
URI of the LDAP Server to connect to. Supported URI schemes are 'ldaps://' and 'ldap://' |
|
string |
~/.ocis/idm/ldap.crt |
Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the LDAP service. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH:/idm. |
|
bool |
false |
Disable TLS certificate validation for the LDAP connections. Do not set this in production environments. |
|
string |
uid=libregraph,ou=sysusers,o=libregraph-idm |
LDAP DN to use for simple bind authentication with the target LDAP server. |
|
string |
|
Password to use for authenticating the 'bind_dn'. |
|
bool |
false |
If set to true, rely on the LDAP Server to generate a unique ID for users and groups, like when using 'entryUUID' as the user ID attribute. |
|
bool |
true |
Use the 'Password Modify Extended Operation' for updating user passwords. |
|
bool |
true |
Allow creating, modifying and deleting LDAP users via the GRAPH API. This can only be set to 'true' when keeping default settings for the LDAP user and group attribute types (the 'OCIS_LDAP_USER_SCHEMA_* and 'OCIS_LDAP_GROUP_SCHEMA_* variables). |
|
bool |
false |
Signals that the server has the refint plugin enabled, which makes some actions not needed. |
|
string |
ou=users,o=libregraph-idm |
Search base DN for looking up LDAP users. |
|
string |
sub |
LDAP search scope to use when looking up users. Supported scopes are 'base', 'one' and 'sub'. |
|
string |
|
LDAP filter to add to the default filters for user search like '(objectclass=ownCloud)'. |
|
string |
inetOrgPerson |
The object class to use for users in the default user search filter ('inetOrgPerson'). |
|
string |
LDAP Attribute to use for the email address of users. |
|
|
string |
displayName |
LDAP Attribute to use for the displayname of users. |
|
string |
uid |
LDAP Attribute to use for username of users. |
|
string |
owncloudUUID |
LDAP Attribute to use as the unique ID for users. This should be a stable globally unique ID like a UUID. |
|
bool |
false |
Set this to true if the defined 'ID' attribute for users is of the 'OCTETSTRING' syntax. This is required when using the 'objectGUID' attribute of Active Directory for the user ID’s. |
|
string |
ownCloudUserType |
LDAP Attribute to distinguish between 'Member' and 'Guest' users. Default is 'ownCloudUserType'. |
|
string |
ownCloudUserEnabled |
LDAP Attribute to use as a flag telling if the user is enabled or disabled. |
|
string |
attribute |
An option to control the behavior for disabling users. Supported options are 'none', 'attribute' and 'group'. If set to 'group', disabling a user via API will add the user to the configured group for disabled users, if set to 'attribute' this will be done in the ldap user entry, if set to 'none' the disable request is not processed. Default is 'attribute'. |
|
string |
cn=DisabledUsersGroup,ou=groups,o=libregraph-idm |
The distinguished name of the group to which added users will be classified as disabled when 'disable_user_mechanism' is set to 'group'. |
|
string |
ou=groups,o=libregraph-idm |
Search base DN for looking up LDAP groups. |
|
string |
ou=groups,o=libregraph-idm |
Parent DN under which new groups are created. This DN needs to be subordinate to the 'GRAPH_LDAP_GROUP_BASE_DN'. This setting is only relevant when 'GRAPH_LDAP_SERVER_WRITE_ENABLED' is 'true'. It defaults to the value of 'GRAPH_LDAP_GROUP_BASE_DN'. All groups outside of this subtree are treated as readonly groups and cannot be updated. |
|
string |
sub |
LDAP search scope to use when looking up groups. Supported scopes are 'base', 'one' and 'sub'. |
|
string |
|
LDAP filter to add to the default filters for group searches. |
|
string |
groupOfNames |
The object class to use for groups in the default group search filter ('groupOfNames'). |
|
string |
cn |
LDAP Attribute to use for the name of groups. |
|
string |
member |
LDAP Attribute that is used for group members. |
|
string |
owncloudUUID |
LDAP Attribute to use as the unique id for groups. This should be a stable globally unique ID like a UUID. |
|
bool |
false |
Set this to true if the defined 'ID' attribute for groups is of the 'OCTETSTRING' syntax. This is required when using the 'objectGUID' attribute of Active Directory for the group ID’s. |
|
bool |
false |
Enable LDAP support for managing education related resources. |
|
string |
|
Search base DN for looking up LDAP schools. |
|
string |
|
LDAP search scope to use when looking up schools. Supported scopes are 'base', 'one' and 'sub'. |
|
string |
|
LDAP filter to add to the default filters for school searches. |
|
string |
|
The object class to use for schools in the default school search filter. |
|
string |
|
LDAP Attribute to use for the name of a school. |
|
string |
|
LDAP Attribute to use for the number of a school. |
|
string |
|
LDAP Attribute to use as the unique id for schools. This should be a stable globally unique ID like a UUID. |
|
int |
0 |
When setting a 'terminationDate' for a school, require the date to be at least this number of days in the future. |
|
string |
127.0.0.1:9233 |
The address of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. Set to a empty string to disable emitting events. |
|
string |
ocis-cluster |
The clusterID of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. |
|
bool |
false |
Whether to verify the server TLS certificates. |
|
string |
|
The root CA certificate used to validate the server’s TLS certificate. If provided GRAPH_EVENTS_TLS_INSECURE will be seen as false. |
|
bool |
false |
Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between the services.. |
|
string |
|
Machine auth API key used to validate internal requests necessary to access resources from other services. |
|
string |
|
The URL to access keycloak. |
|
string |
|
The client id to authenticate with keycloak. |
|
string |
|
The client secret to use in authentication. |
|
string |
|
The realm the client is defined in. |
|
string |
|
The realm users are defined. |
|
bool |
false |
Disable TLS certificate validation for Keycloak connections. Do not set this in production environments. |
YAML Example
Note that the filename shown below has been chosen on purpose.
See the Configuration File Naming for details when setting up your own configuration.
# Autogenerated
# Filename: graph-config-example.yaml
tracing:
enabled: false
type: ""
endpoint: ""
collector: ""
log:
level: ""
pretty: false
color: false
file: ""
cache:
store: memory
nodes: []
database: ocis
table: roles
ttl: 336h0m0s
size: 0
debug:
addr: 127.0.0.1:9124
token: ""
pprof: false
zpages: false
http:
addr: 127.0.0.1:9120
root: /graph
tls:
enabled: false
cert: ""
key: ""
apitoken: ""
cors:
allow_origins:
- '*'
allow_methods:
- GET
- POST
- PUT
- PATCH
- DELETE
- OPTIONS
allow_headers:
- Authorization
- Origin
- Content-Type
- Accept
- X-Requested-With
- X-Request-Id
- Purge
- Restore
allow_credentials: true
api:
group_members_patch_limit: 20
graph_username_match: default
graph_assign_default_user_role: true
reva:
address: com.owncloud.api.gateway
tls:
mode: ""
cacert: ""
token_manager:
jwt_secret: ""
grpc_client_tls: null
application:
id: ""
displayname: ownCloud Infinite Scale
spaces:
webdav_base: https://localhost:9200
webdav_path: /dav/spaces/
default_quota: "1000000000"
extended_space_properties_cache_ttl: 60000000000
users_cache_ttl: 60000000000
groups_cache_ttl: 60000000000
identity:
backend: ldap
ldap:
uri: ldaps://localhost:9235
cacert: ~/.ocis/idm/ldap.crt
insecure: false
bind_dn: uid=libregraph,ou=sysusers,o=libregraph-idm
bind_password: ""
use_server_uuid: false
use_password_modify_exop: true
write_enabled: true
refint_enabled: false
user_base_dn: ou=users,o=libregraph-idm
user_search_scope: sub
user_filter: ""
user_objectclass: inetOrgPerson
user_mail_attribute: mail
user_displayname_attribute: displayName
user_name_attribute: uid
user_id_attribute: owncloudUUID
user_id_is_octet_string: false
user_type_attribute: ownCloudUserType
user_enabled_attribute: ownCloudUserEnabled
disable_user_mechanism: attribute
ldap_disabled_users_group_dn: cn=DisabledUsersGroup,ou=groups,o=libregraph-idm
group_base_dn: ou=groups,o=libregraph-idm
group_create_base_dn: ou=groups,o=libregraph-idm
group_search_scope: sub
group_filter: ""
group_objectclass: groupOfNames
group_name_attribute: cn
group_member_attribute: member
group_id_attribute: owncloudUUID
group_id_is_octet_string: false
education_resources_enabled: false
educationconfig:
school_base_dn: ""
school_search_scope: ""
school_filter: ""
school_objectclass: ""
school_name_attribute: ""
school_number_attribute: ""
school_id_attribute: ""
school_termination_min_grace_days: 0
events:
endpoint: 127.0.0.1:9233
cluster: ocis-cluster
tls_insecure: false
tls_root_ca_certificate: ""
enable_tls: false
machine_auth_api_key: ""
keycloak:
base_path: ""
client_id: ""
client_secret: ""
client_realm: ""
user_realm: ""
insecure_skip_verify: false