Invitations

Abstract

The invitations service provides an Invitation Manager that can be used to invite external users, aka guests, to an organization.

Users invited via the Invitation Manager (via the libre graph API) will have the userType="Guest".
Users belonging to the organization have the userType="Member".

The corresponding CS3 API user types used to reperesent this are: USER_TYPE_GUEST and USER_TYPE_PRIMARY.

Provisioning Backends
- Keycloak
  - Keycloak Realm Configuration
Backend Configuration
Bridging Provisioning Delay
Example Yaml Config

Provisioning Backends

When Infinite Scale is used via the IDM service for the user management, users are created using the /graph/v1.0/users endpoint via the libre graph API. For larger deployments, the Keycloak admin API can be used to provision users. In a future step, the endpoint, credentials and body might be made configurable using templates.

Keycloak

The default and currently only available backend used to handle invitations is Keycloak. Keycloak is an open source identity and access management (IAM) system which is also integrated by other Infinite Scale services as an authentication and authorization backend.

Keycloak Realm Configuration

See the example configuration json file of a Keycloak realm the backend will work with. This file includes the invitations client, which is relevant for this service.

To use the example json, set the INVITATIONS_KEYCLOAK_CLIENT_ID setting to invitations, though any other client ID can be configured.

Importing this example into Keycloak will give you a realm that federates with an LDAP server, has the right clients configured and all mappers correctly set. Be sure to set all the credentials after the import, as they will be disabled.

The most relevant bits are the mappers for the OWNCLOUD_ID and OWNCLOUD_USER_TYPE user properties.

Backend Configuration

After Keycloak has been configured, the invitation service needs to be configured with the following environment variables:

INVITATIONS_KEYCLOAK_BASE_PATH: The URL to access Keycloak.
INVITATIONS_KEYCLOAK_CLIENT_ID: The client ID of the client to use. In the above example, invitations is used.
INVITATIONS_KEYCLOAK_CLIENT_SECRET: The client secret used to authenticate. This can be found in the Keycloak UI.
INVITATIONS_KEYCLOAK_CLIENT_REALM: The realm where the client was added. In the example above, ocis is used.
INVITATIONS_KEYCLOAK_USER_REALM: The realm where to add the users. In the example above, ocis is used.
INVITATIONS_KEYCLOAK_INSECURE_SKIP_VERIFY: If set to true, the verification of the Keycloak HTTPS certificate is skipped. This is not recommended in production environments.

Bridging Provisioning Delay

Consider that when a guest account has to be provisioned in an external user management, there might be a delay between creating the user and the user being available in the local Infinite Scale system.

Example Yaml Config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


# Autogenerated
# Filename: invitations-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9269
  token: ""
  pprof: false
  zpages: false
http:
  addr: 127.0.0.1:9265
  root: /graph/v1.0
  cors:
    allow_origins:
    - https://localhost:9200
    allow_methods: []
    allow_headers: []
    allow_credentials: false
  tls:
    enabled: false
    cert: ""
    key: ""
keycloak:
  base_path: ""
  client_id: ""
  client_secret: ""
  client_realm: ""
  user_realm: ""
  insecure_skip_verify: false
token_manager:
  jwt_secret: ""

Environment Variables

Name	Type	Default Value	Description
OCIS_TRACING_ENABLED INVITATIONS_TRACING_ENABLED	bool	false	Activates tracing.
OCIS_TRACING_TYPE INVITATIONS_TRACING_TYPE	string		The type of tracing. Defaults to ‘’, which is the same as ‘jaeger’. Allowed tracing types are ‘jaeger’ and ’’ as of now.
OCIS_TRACING_ENDPOINT INVITATIONS_TRACING_ENDPOINT	string		The endpoint of the tracing agent.
OCIS_TRACING_COLLECTOR INVITATIONS_TRACING_COLLECTOR	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.
OCIS_LOG_LEVEL INVITATIONS_LOG_LEVEL	string		The log level. Valid values are: ‘panic’, ‘fatal’, ’error’, ‘warn’, ‘info’, ‘debug’, ’trace’.
OCIS_LOG_PRETTY INVITATIONS_LOG_PRETTY	bool	false	Activates pretty log output.
OCIS_LOG_COLOR INVITATIONS_LOG_COLOR	bool	false	Activates colorized log output.
OCIS_LOG_FILE INVITATIONS_LOG_FILE	string		The path to the log file. Activates logging to this file if set.
INVITATIONS_DEBUG_ADDR	string	127.0.0.1:9269	Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.
INVITATIONS_DEBUG_TOKEN	string		Token to secure the metrics endpoint.
INVITATIONS_DEBUG_PPROF	bool	false	Enables pprof, which can be used for profiling.
INVITATIONS_DEBUG_ZPAGES	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
INVITATIONS_HTTP_ADDR	string	127.0.0.1:9265	The bind address of the HTTP service.
INVITATIONS_HTTP_ROOT	string	/graph/v1.0	Subdirectory that serves as the root for this HTTP service.
OCIS_CORS_ALLOW_ORIGINS INVITATIONS_CORS_ALLOW_ORIGINS	[]string	[https://localhost:9200]	A 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. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_METHODS INVITATIONS_CORS_ALLOW_METHODS	[]string	[]	A 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. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_HEADERS INVITATIONS_CORS_ALLOW_HEADERS	[]string	[]	A 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. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_CREDENTIALS INVITATIONS_CORS_ALLOW_CREDENTIALS	bool	false	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.
OCIS_HTTP_TLS_ENABLED	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.
OCIS_HTTP_TLS_CERTIFICATE	string		Path/File name of the TLS server certificate (in PEM format) for the http services.
OCIS_HTTP_TLS_KEY	string		Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services.
OCIS_KEYCLOAK_BASE_PATH INVITATIONS_KEYCLOAK_BASE_PATH	string		The URL to access keycloak.
OCIS_KEYCLOAK_CLIENT_ID INVITATIONS_KEYCLOAK_CLIENT_ID	string		The client ID to authenticate with keycloak.
OCIS_KEYCLOAK_CLIENT_SECRET INVITATIONS_KEYCLOAK_CLIENT_SECRET	string		The client secret to use in authentication.
OCIS_KEYCLOAK_CLIENT_REALM INVITATIONS_KEYCLOAK_CLIENT_REALM	string		The realm the client is defined in.
OCIS_KEYCLOAK_USER_REALM INVITATIONS_KEYCLOAK_USER_REALM	string		The realm users are defined.
OCIS_KEYCLOAK_INSECURE_SKIP_VERIFY INVITATIONS_KEYCLOAK_INSECURE_SKIP_VERIFY	bool	false	Disable TLS certificate validation for Keycloak connections. Do not set this in production environments.
OCIS_JWT_SECRET INVITATIONS_JWT_SECRET	string		The secret to mint and validate jwt tokens.