This core service manages the authentication of users and applications for the access to services within the yuuvis® Momentum cluster.

Characteristics

Function

The yuuvis® authentication service decides for each API request of any user if the access is granted or not. In its configuration, the access conditions can be defined individually for each API endpoint. Thus, permissions in yuuvis® Momentum can be set not only for types of actions and the usage of specific object types, but also directly for API endpoints. It is even possible to allow the usage of an API endpoint for callers without authentication.

Access Authorization for Endpoints

Access permissions can be configured for each endpoint (core API URLs and service URLs) in the yuuvis® API authentication service. For this purpose, endpoint patterns are assigned to access conditions.

For each incoming request, the first condition is determined with an endpoint pattern that matches the request URL. This condition is evaluated and decides whether access is granted or not. Access permissions without access conditions are granted after log in. The requesting client can identify rejected requests by the status code 403 (forbidden).

The access conditions are described in the access attribute of the access permission. User attributes (like user ID, tenant membership or user roles) and request attributes (like IP address or request header) can be used. Complex access conditions can be formed with operators and functions.

By means of the expose flag, endpoints can be made accessible for unauthenticated access. That means that clients can call the endpoint without having to log in first. The access condition for such endpoints can only contain functions for the evaluation of IP addresses and request headers. Access conditions for expose endpoints always have precedence over those with mandatory authentication, even if they are further down in the mapping list. Services that are called via expose endpoints cannot determine the identity of the caller, even if the caller was authenticated by another endpoint. Without the expose flag, access permissions are only granted after authentication.

Access permissions can be limited to specific HTTP methods (method attribute of the access permission). If you omit the specification, then the permission is applied to all HTTP methods. An access permission can contain multiple endpoint patterns and HTTP methods separated by commas.

Access permissions are registered as an authorization.accesses list in the configuration of yuuvis® API authentication-service. If multiple lists are entered, only the last one is applied.

Rules for Endpoint Patterns

• ? placeholder for exactly one random character
• * placeholder for exactly one path segment
• ** placeholder for any number of path segments
• the query string cannot be included in the pattern

Examples:

• /com/t?st.html
  • matches com/test.html but also com/tast.html or com/txst.html
• /com/*.html
  • matches all .html files in the com directory
• /com/**/test.html
  • matches all test.html files underneath the com path
• /org/springframework/**/*.html
  • matches all .html files underneath the org/springframework path
• /org/**/servlet/test.html
  • matches org/springframework/servlet/test.html but also org/springframework/testing/servlet/test.html and org/servlet/test.html

Syntax for Access Conditions

• operators
  • or, and, () - operators for forming complex access conditions
  • == - compares strings
• functions for expose endpoints
  • hasIpAddress('<IP range>') - returns true if the request comes from the passed IP address range
  • hasHeader('<header name>', '<value>') - returns true if the request contains the passed header and its value starts with the passed value
• functions for endpoints with authentication requirement
  • permitAll() - returns true (parentheses can be omitted)
  • denyAll() - returns false (parentheses can be omitted)
  • not(<expression>) - negates passed expression
  • hasIpAddress('<IP-Bereich>') - returns true if the request comes from the passed IP address range
  • principal.getId() - returns caller’s ID
  • principal.getUsername() - returns the login name of the user account (this can occur several times in multi-tenancy systems)
  • principal.getTenant() - returns the caller’s tenant
  • hasAuthority('<user role>') - returns true if the caller has the passed role
  • hasAnyAuthority('<role1>','<role2>',...) - returns true if the caller has one of the passed roles

Combined Examples

Callers from the IP address range 192.168.1.0/24 can access managed endpoints without authentication. All other callers must login and have one of the following roles: EXAMPLE_ADMIN_ROLE or EXAMPLE_INTEGRATOR_ROLE.

authorization.accesses:
  - endpoints: /manage/**,/*/manage/**
    expose: true
    access: hasIpAddress('192.168.1.0/24')
  - endpoints: /manage/**,/*/manage/**
    access: hasAnyAuthority('EXAMPLE_ADMIN_ROLE','EXAMPLE_INTEGRATOR_ROLE')

Endpoints for using the web application are accessible for all authenticated users.

authorization.accesses:
  - endpoints: /api/dms/**,/api-web/**,/api/sandbox/renditions/**

The yuuvis® core API is read-only. access: permitAll can be omitted as it corresponds to the default setting. The prohibition condition for the POST method and DELETE method can also be omitted, because the access to unlisted endpoints is generally denied.

authorization.accesses:
  - endpoints: /api/dms/objects/**
    method: POST,DELETE
    access: denyAll
  - endpoints: /api/dms/objects/**
    method: GET
    access: permitAll
  - endpoints: /api/dms/objects/search/**
    method: POST
    access: permitAll

Only users of the default tenant and dev tenant may use custom services.

authorization.accesses:
  - endpoints: /custom/**
    access: principal.getTenant() == 'default' or principal.getTenant() == 'dev'

Users of the dev tenant are denied access to the custom service. All other users have access.

authorization.accesses:
  - endpoints: /custom/**
    access: not(principal.getTenant() == 'dev')

The user with the ID 78d3b2a8535b has unrestricted document access. All other users only have access to the latest document version.

authorization.accesses:
  - endpoints: /api/dms/objects/*/versions/**
    access: principal.getId() == '78d3b2a8535b'
  - endpoints: /api/dms/objects/**

The users historyTracker of all tenants only have access to the document history. They have no access to other document information. All other users have unrestricted document access.

authorization.accesses:
  - endpoints: /api/dms/objects/*/history
  - endpoints: /api/dms/objects/**
    access: not(principal.getUsername() == 'historyTracker')

Accessing External Services via Authentication Service

The AUTHENTICATION service manages the access to the yuuvis® Momentum API gateway. With a suitable configuration, also the access to external services running in the same Kubernetes cluster can be managed via the AUTHENTICATION service of yuuvis® Momentum.

>> Accessing External Services via AUTHENTICATION Service

Internal JSON Web Tokens

Each call of a yuuvis® Momentum endpoint is routed through the AUTHENTICATION service. After successful authentication, an internal JSON Web Token (JWT) is created and assigned to the call containing user-specific information. This JWT authorizes the call in every service within the data processing chain.

Structure of internal JWTs

The internal JWTs consist of

• header with signature algorithm RS256,
• payload and
• as of 2021 Autumn, a signature of header and payload.

These three parts are included as .-separated Base64-encoded blocks in each authorization request header for API calls, optionally encrypted.

The payload contains key-value pairs specifying the following parameters:

An example payload is displayed in the code block below.

{
    "sub": "3cfaf962-b254-45c8-b0e9-82f79f2c26ee",
    "tenant": "sales-office",
    "name": "mustermann",
    "accessToken": "Bearer eyJhbGciOiJS...",
    "iat": 1621324798,
    "exp": 1621325698,
    "authorities": [
        "YUUVIS_DEFAULT",
        "YUUVIS_MANAGE_SETTINGS"
    ]
}

Validation of internal JWTs (as of version 2021 Autumn)

In order to prevent unauthorized access from outside by faking the JWT, its signature can be used for an additional validation of the caller's authorization. The validation is provided by the internal endpoint /authentication/jwt/verify/** of the AUTHENTICATION service. In order to activate the validation, follow the link below.

>> Validating Internal JSON Web Tokens

Configuration

The yuuvis® Momentum configuration files for the operation in the Kubernetes cluster are stored on the Git Server configured in the system. In order to change the configuration of a service, you need to access the Git repository. 

Parameters in Profiles

The following parameters are referenced from the corresponding profiles. Click a profile in order to display descriptions and default values of the corresponding parameters.

The values for the parameters can be modified as described here.
>> Configuring Services using Profiles.