User Authentication Passing#
Introduction#
The system does not understand the concept of users directly, it is only possible to pass existing credentials along to external systems. Credentials must exist in the form of HTTP headers on any requests the system receives. External systems are then required to perform authorization checks with these headers when 3D data is accessed or downloaded.
Warning
Configuration of authentication forwarding rules is required in order to pass any authentication tokens, no matter the method described here. No headers ever leave the system in the default configuration.
Forwarding Configuration#
All configuration takes place in values.yaml.
Rules must be configured which define which headers are allowed to be sent to which backend addresses. Preferably this is done directly via URNs:
# Set data pools for external data sources. These define how data is accessed or
# how inputs should be rewritten. The system will attempt to download data from
# the given urlTemplate and use the data as input for transcoding.
#
# Either "urn" or "regex" must be set. A URN rule provides a more simplified way
# to define abstract identifiers for data sources. Regex allows for more complex
# matching of URLs. A URN rule must always be accompanied by a urlTemplate, a
# regex rule can be used without requiring a rewrite.
#
# For urlTemplates in URN rules, ${n} is the n-th value in the URN separated
# after urn:namespace:specifier:xxx:yyy.
# For example, urn:x-i3d:shape:sphere:large would map ${1} -> sphere and
# ${2} -> large.
#
# For regex templates, ${n} is the n-th capture group value in the regex.
# Capture groups are defined by parentheses in the regex. See
# https://pkg.go.dev/regexp/syntax for an overview of available regex syntax.
# If no urlTemplate is set, the incoming URL is preserved and not rewritten.
datapools:
- urn: urn:customer:document-uuid
urlContentType: # optional
- "openjt"
urlTemplate: https://download.example.com/documents/${1}.jt
authUrlTemplate: https://auth.example.com/documents/${1}.jt # optional
# Set any authorization header names which must be passed to data backends.
# These will be copied from incoming client requests and used while downloading
# data or performing authorization requests against the backends.
# No client headers or cookies will be forwarded to any backends by default as
# this could leak client credentials to arbitrary URLs.
forwardHeaders: [ "Authorization" ] # optional
forwardCookies: [ "CookieName" ] # optional
The fields forwardCookies and forwardHeaders can be set in order to
specify which cookies (by name) or which headers (by name) will be forwarded
(if present) when accessing any resource to which the URN points.
If all cookies should be forwarded, regardless of name, Cookies can be added
to forwardHeaders.
Caching Configuration#
External backends can be exposed to a high load if caching is not configured. As the system does not understand users directly, caching can only work effectively if it is possible to derive a user ID from an authentication token. OpenID-Connect provides this functionality and can be configured if available.
If OpenID-Connect is not available, it is possible to also cache directly by header value, but this may be unstable if values frequently change on a request by request basis.
# Configure options relating to required authorization headers and caching.
auth:
caching:
# Address of the used openid provider. For google this would be
# https://accounts.google.com
# .well-known/openid-configuration is appended to this URL in order to
# discover relevant endpoints.
oidcProviderEndpoint:
# Name of the header which contains the OIDC token. If a provider endpoint
# is given, the service will attempt to validate this token as an
# OpenID-Connect JWT token and use the contained user ID to cache
# authorization responses. Without a provider endpoint, the token
# value will be used to cache authorization responses.
oidcHeader:
# Duration for which to cache an authorization result. Only successful
# authorizations are cached. Must be set to 0s if no header is given.
# Otherwise responses will be cached for the given duration and used for
# every user.
duration: 0s
Custom Client Header Configuration#
There are two use-cases based on how authentication tokens are acquired:
Applications always have SSO authentication tokens set by cookies
Applications must perform authentication flow and set headers themselves
For the second case, the backend must be configured to allow these to be set in CORS scenarios:
# Configure options relating to required authorization headers and caching.
auth:
# Sets a list of headers to include in any Access-Control-Allow-Headers preflight
# responses. This is required when setting headers manually via the webvis-API.
# For example, if clients are required to attach credentials not in cookie form,
# the specific headers must be allowed here.
clientHeaders:
- "Custom-Authorization"
- "X-Requested-With"