Authentication

AV can support both token based and basic authentication, either one or the other or both at the same time. Credentials need to be sent with every request, in the Authorization header.

Base configuration parameters used:

• auth.enabled - enables/disables authentication support
• fallback.username - username that will be used whenever authentication is not enabled

Basic authentication configuration

For basic authentication users, roles and credentials are stored in properties files that are deployed together with the adapter.

Configuration parameters used:

• quarkus.security.users.file.enabled - enables reading of users/credentials/roles from properties files
• quarkus.security.users.file.roles - filename of file that contain the user role mappings, note that this files must be on the classpath
• quarkus.security.users.file.users - filename of file that contain the user credentials, note that this files must be on the classpath

Token based authentication

Only JWT tokens are supported when using token based authentication.

Configuration parameters used:

• auth.jwt.enabled - enables/disables JWT token based authentication support
• auth.jwt.alg - The signature algorithm used for the JWT token
• auth.jwt.issuer - JWT issuer the tokens need to match
• auth.jwt.issuer.enforced - If set to false, issuer matching is skipped
• auth.jwt.jwk.filename - filename or URI to the JWT token key set used to verify the token signatures
• auth.jwt.username - JWT claim name that contain the username of the user
• auth.jwt.groups - JWT claim name that contain roles and groups of the user
• auth.jwt.superuser.client_ids - JWT client ids that should be given implicit superuser access, comma separated string
• auth.jwt.superuser.groups - Groups that should be given implicit superuser access, comma separated string
• auth.jwt.group.expansion - Group expansions to apply on JWT groups, any matching groups will be added to the group list for the principal, example auth.jwt.group.expansion."Some group"=av_viewer

Role based access control

Whenever authentication is enabled, role based access is implicitly enabled. Roles for a user is checked by looking for the role name in the list of groups/roles configured in the authentication source (see above for more information on authentication).

The following roles exist in the system:

• superuser - Gives the user all roles, and implicit access to all entities in the system, use with care.
• asset_read - Can list and retrieve asset information
• asset_write - Can modify basic asset data, create new assets (including ingesting readable files)
• asset_delete - Can delete assets
• metadata_read - Can view asset metadata
• metadata_write - Can modify asset metadata
• metadata_delete - Can delete asset metadata
• metadata_group_read - Can view asset metadata groups
• metadata_group_write - Can modify asset metadata groups
• metadata_group_delete - Can delete asset metadata groups
• timespan_read - Can view asset timespans
• timespan_write - Can modify asset timespans
• timespan_delete - Can delete asset timespans
• timespan_export - Can request timespan export
• access_read - Can view ACL information
• access_write - Can modify ACL information
• access_delete - Can delete ACL entries
• storage_read - Can view storages
• storage_write - Can modify storages
• storage_delete - Can delete storages
• storage_metadata_read - Can view storage metadata
• storage_metadata_write - Can modify storage metadata
• storage_metadata_delete - Can delete storage metadata
• storage_file_read - Can view storage file information
• storage_file_write - Can index new storage file locations
• storage_file_delete - Can delete physical files on storages
• file_read - Can view file information, except for files with tag original
• file_read_original - Can view file information for files with tag original
• file_write - Can modify file information
• file_delete - Can delete files, including physical files
• file_metadata_read - Can view file metadata
• file_metadata_write - Can modify file metadata
• file_metadata_delete - Can delete file metadata
• job_view - Can view job information of users own jobs
• job_read - Can view job information
• job_write - Can modify job information
• job_delete - Can abort jobs
• poster_create - Can request new posters to be created
• render - Can request timeline render operations
• usage_read - Can view usage reports
• settings_read - Base role for reading settings but more specific settings_read_* is also needed (see below)
• settings_read_av_safe_area - Can read settings of type av_safe_area
• settings_read_av_poster_room_overlay - Can read settings of type av_poster_room_overlay
• settings_read_av_poster_room_image_preset - Can read settings of type av_poster_room_image_preset
• settings_read_all - Can read all types of settings (with this role any specific settings_read_* is not needed)
• settings_write - Base role for writing settings but more specific settings_write_* is also needed (see below)
• settings_write_av_safe_area - Can write settings of type av_safe_area. Note that settings_read_all or settings_read_av_safe_area is also required.
• settings_write_av_poster_room_overlay - Can write settings of type av_poster_room_overlay. Note that settings_read_all or settings_read_av_poster_room_overlay is also required.
• settings_write_av_poster_room_image_preset - Can write settings of type av_poster_room_image_preset. Note that settings_read_all or settings_read_av_poster_room_image_preset is also required.
• settings_write_all - Can write all types of settings (with this role any specific settings_write_* is not needed). Note that settings_read_all or settings_read_* is also required.
• settings_delete - Can delete settings. Note that roles for reading and writing the setting to delete is also required.
• analysis_write - Can start enrich jobs for assets

Access control lists

Access control in AV is based around the concept of no access by default, all access is explicitly given by directives either on assets or storages. The one exception to this is that users with the role superuser have full access to everything.

Currently, access in AV is assigned on a per entity basis, there is no propagation of access between assets/storages. When a new asset is ingested, only the user that requested the ingest will have access (and implicitly also users with the superuser role), and that user can then choose to share the asset with others.

NOTE: we have support in the backend for ACL on storages, however we have no support for this in the frontend yet, therefore this should not be enabled yet.

Access types

At the time of writing this we have three access types:

• read - gives read access to the asset/storage, this includes being able to access files for assets and non-ingested files for storages
• write - gives write access to the asset/storage
• modify_all_access - gives access modification access to the asset/storage

In addition to this, customers can add any custom access type(s) which can control things on their end, but they will not affect how assets are accesible in our backend.

Ingest

When ingesting an asset, the user can optionally provide the access set in the ingest request. On top of this, the calling user will always be given full access to the asset (meaning the user will get access types read, write and modify_all_access).

Retrieving asset access information

When retrieving assets from the backend, either using the asset list request or single asset lookup, the access information can be returned if the content ACCESS is requested, i.e. http://localhost:8080/asset/10?content=ACCESS. If this content is requested, the calling users access will always be computed and returned on the following format:

{
    "id": "10",
    "callerAccess": {
        "read": true,
        "write": false,
        "modify_acl_access": false
    }
}

If the calling user have modify ACL access, the raw access data will also be returned:

{
    "id": "10",
    "callerAccess": {
        "read": true,
        "write": true,
        "modify_acl_access": true
    },
    "access": [
        {
            "principalType": "USER",
            "principal": "morten",
            "accessTypes": [
                "read",
                "write"
            ]
        },
        {
            "principalType": "GROUP",
            "principal": "Content viewers",
            "accessTypes": [
                "read"
            ]
        }
    ]
}

Retrieving storage access information

For storages, we will always return the access information (i.e. there is not content parameter), on the same format as for assets, see above for more information.

Access API

To modify access or retrieve only the raw access data, use:

• for assets - GET/POST /asset/X/access
• for storages - GET/POST /storage/Y/access

These endpoints will give/take raw access data as follows:

[
    {
        "principalType": "USER",
        "principal": "morten",
        "accessTypes": [
            "read",
            "write"
        ]
    },
    {
        "principalType": "GROUP",
        "principal": "Content viewers",
        "accessTypes": [
            "read"
        ]
    }
]

Note that when modifying access for an asset/storage, the full access data must be provided, There is no support for adding/deleting partial access, any old access that is not in the request will be removed.

Configuring access control

The following configuration parameters on the adapter controls ACL:

• auth.enabled - enables/disables authentication, for access control to be enabled authentication must first be enabled
• acl.enabled - enables/disables access control for assets and ingested files
• acl.storage.enabled - enables/disables access control for storages and non-ingested files

Principal (user/group) access management

To enable access management in the frontend, a principal api is available that can present principals from the following sources:

• Properties file injected in the adapter configuration
• Keycloak

To enable this api:

• principal.enabled - Enable/disable the principal api

Configuring principals from properties file

We can supply users/groups from a properties file. This file looks like the following:

{
  "groups": [
    {
      "id": "some_group",
      "name": "Some group"
    }
  ],
  "users": [
    {
      "id": "user",
      "username": "user",
      "email": "user@codemill.se"
      "name": "Some user"
    }
  ]
}

To make the adapter use this file as a source for principals, set:

• principal.properties.file=/path/to/principals.json

Configuring principals from keycloak

In order to read principal information from keycloak, a user must first be created in Keycloak that have the following roles:

• realm-management: view-users

To make the adapter use this user to read principal information from keycloak:

• principal.keycloak.enabled=true
• principal.keycloak.username=username - the username of the user created above in keycloak
• principal.keycloak.password=1234 - the password for the user created above in keycloak
• principal.keycloak.client_id=admin-cli - the client in keycloak to use to fetch principal data
• principal.keycloak.realm=accurate-video - the keycloak realm
• principal.keycloak.url=https://keycloak.io/auth - base keycloak url

Collections

By default, collections will propagate the access entries on itself to its children. This can however be configured using the configuration variable acl.propagate.filter. These filters describe what collections should propagate their access control lists to children.

Example

acl.propagate.filter=source:str_eq=portal,type:string_in=series\\,season\\,episode

In this example only collections that have the metadata field source set to portal and metadata field type set to one of ['series', 'season', 'episode'] will propagate their ACL entries. All other collections will not propagate access to their children.

Do note that currently there is no way to see propagated access groups when requesting access for a child asset. The only way currently to see this is to call the API endpoint /asset/X/access/effective.