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 the URN mapping rules per data gateway. See the integration documentation for
# motivation and concepts behind data gateways and URN mappings.
#
# For templates, $(n) is the n-th value in the URN separated after urn:namespace:specifier:xxx
# e.g.: urn:x-i3d:shape:sphere ($(1) == sphere)
dataGateways:
exampleGateway:
- namespace: customer
specifier: document-uuid
urlContentType: [ "openjt" ]
urlTemplate: https://download.example.com/documents/$(1).jt
authUrlTemplate: https://auth.example.com/documents/$(1).jt
forwardCookies: [ "Cookie1" ]
forwardHeaders: [ "Header1" ]
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.
Alternatively, it is also possible to define a regular expression which defines a set of backends to forward headers to:
# Configure options relating to required authorization headers and caching.
auth:
# 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.
# If dataGateways are defined, forwardHeaders or forwardCookies fields can also be
# defined there on a per-rule basis. This should be preferred as it is more robust
# than regex matching URLs.
# In either case, rules from URN definitions are applied first, after which the
# regex rules defined here are applied on the URL generated by resolving the URN.
forwardHeaders:
- match: "https://server1.*"
headers: [ "Header1", "Header2" ]
cookies: [ "Cookie1", "Cookie2" ]
- match: "https://server2.*"
headers: [ "Header1", "Header3" ]
cookies: [ "Cookie1", "Cookie3" ]
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 aquired:
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 specfic headers must be allowed here.
clientHeaders:
- "Custom-Authorization"
- "X-Requested-With"