Authentication

Authentication in DeltaFi is handled at the Kubernetes Ingress level. Each request that comes in is checked against the deltafi-auth service. This service can be configured for Basic Authentication (default) or Client Certificate Authentication. The system can only run in one mode at a time.

Basic Authentication

By default, DeltaFi is configured for Basic Authentication. The default user is admin and the password can be set by running the following TUI command:

 deltafi set-admin-password

Additional users can be added on the Users page in the UI.

Client Certificate Authentication

When configuring a system for Client Certificate Authentication, it is recommended to start with Basic Authentication, set up your users, and then switch to Client Certificate Authentication.

Adding a User with a Client Certificate

Before switching to Client Certificate Authentication, be sure to add a new user with a Distinguished Name (DN).

1. Go to the Users page in the UI.
2. Click on the Add User button in the top right.
3. Enter the Name of the new user.
4. In the Authentication section, click on the Certificate tab.

• You will see a warning stating that the authentication mode is currently set to basic and that this must be set to cert before changes will take effect. This will be done in the next section.

1. Enter the Distinguished Name (DN) of the user's client certificate.
2. Assign the user one or more Roles (described below).
3. Click the Save button.

Note: You can also add a Distinguished Name (DN) to an existing user. It will be ignored until Client Certificate Authentication is enabled.

Enabling Client Certificate Authentication

To enable Client Certificate Authentication (and disable Basic Authentication), complete the following steps:

1. Identify and obtain (in PEM format) the certificate chain for the Certificate Authorities that issued the client certificates you want to accept. Store this chain in a file named ca-chain.crt.
2. Create a Kubernetes secret in the deltafi namespace called auth-secret that includes the certificate chain from the previous step.

kubectl create secret generic auth-secret --from-file=ca.crt=ca-chain.crt

1. Set deltafi.auth.mode to cert in your site.values.yaml file (as described in the Install DeltaFi Core section.)

    deltafi:
      auth:
        mode: cert

1. Update DeltaFi with the configuration from the previous step.

deltafi update --values ~/site.values.yaml

Visiting the UI should no longer ask for a password and instead, look for a client certificate that satisfies both of the following criteria:

1. Is signed by one of the Certificate Authorities in the auth-secret secret.
2. Has a Distinguished Name (DN) that matches that of a User in the system.

Role-Based Access Control

Authorization in DeltaFi is built on a Role-Based Access Control (RBAC) model. Everything in DeltaFi is restricted to specific Permissions, Permissions are assigned to Roles, and Roles are assigned to Users. Users cannot be assigned Permissions directly - they must be assigned through one or more Roles.

                               ┌────────────┐        ┌────────────┐
                    ┌──────────┤    Role    ├────────┤ Permission │
                    │          └────────────┘        └────────────┘
                    │
         ┌──────────┴─┐                              ┌────────────┐
         │    User    │                   ┌──────────┤ Permission │
         └──────────┬─┘                   │          └────────────┘
                    │                     │
                    │          ┌──────────┴─┐        ┌────────────┐
                    └──────────┤    Role    ├────────┤ Permission │
                               └──────────┬─┘        └────────────┘
                                          │
                                          │          ┌────────────┐
                                          └──────────┤ Permission │
                                                     └────────────┘

Permissions

Permissions in DeltaFi are static and do not change between releases.

Name	Category	Description
Admin	Administration	Full system access
UIAccess	General	Access to the UI
StatusView	General	View system status
StatusPause	General	Pause and resume system status checks
DashboardView	General	View the UI dashboard
VersionsView	General	View running versions
MetricsAdmin	Metrics	Admin role in Grafana
MetricsView	Metrics	Viewer role in Grafana
MetricsEdit	Metrics	Editor role in Grafana
SurveyCreate	Metrics	Post survey metrics into the system
DeltaFileMetadataView	DeltaFiles	Query and view DeltaFile metadata
DeltaFileMetadataWrite	DeltaFiles	Update DeltaFile metadata
DeltaFileContentView	DeltaFiles	View DeltaFile content
DeltaFileReplay	DeltaFiles	Replay DeltaFiles
DeltaFileResume	DeltaFiles	Resume DeltaFiles in an ERROR stage
DeltaFileAcknowledge	DeltaFiles	Acknowledge DeltaFiles in an ERROR stage
DeltaFileCancel	DeltaFiles	Cancel processing of a DeltaFile
DeltaFileUserNote	DeltaFiles	Add user notes to a DeltaFile
DeltaFilePinning	DeltaFiles	Pin or unpin a DeltaFile
DeltaFileIngress	DeltaFiles	Ingress DeltaFiles
DeltaFileExport	DeltaFiles	Export DeltaFiles
DeltaFileImport	DeltaFiles	Import DeltaFiles
FlowView	Flows	View flows
FlowValidate	Flows	Validate flows
FlowUpdate	Flows	Change flow state and update flows
FlowPlanDelete	Flows	Remove flow plans from the system plugin
FlowPlanCreate	Flows	Save flow plans in the system plugin
PluginsView	Plugins	View installed plugins
PluginInstall	Plugins	Install plugins
PluginUninstall	Plugins	Uninstall plugins
PluginVariableUpdate	Plugins	Edit plugin variables
SystemPropertiesRead	System Properties	View System Properties
SystemPropertiesUpdate	System Properties	Edit System Properties
DeletePolicyCreate	Delete Policies	Create Delete Policies
DeletePolicyRead	Delete Policies	View Delete Policies
DeletePolicyUpdate	Delete Policies	Edit Delete Policies
DeletePolicyDelete	Delete Policies	Delete Delete Policies
SnapshotCreate	Snapshots	Create Snapshots
SnapshotRead	Snapshots	View Snapshots
SnapshotDelete	Snapshots	Delete Snapshots
SnapshotRevert	Snapshots	Revert the system to a Snapshot
UserCreate	Users	Create Users
UserRead	Users	View Users
UserUpdate	Users	Edit Users
UserDelete	Users	Delete Users
RoleCreate	Roles	Create Roles
RoleRead	Roles	View Roles
RoleUpdate	Roles	Edit Roles
RoleDelete	Roles	Delete Roles
EventCreate	Events	Create Events
EventRead	Events	View Events
EventUpdate	Events	Edit Events
EventDelete	Events	Delete Events
EventAcknowledge	Events	Acknowledge Events
StressTest	Stress Tests	Execute Stress Tests
IntegrationTestUpdate	Integration Tests	Save and start integration tests
IntegrationTestView	Integration Tests	View integration test results
IntegrationTestDelete	Integration Tests	Delete completed integration test results
ResumePolicyApply	Resume Policies	Apply Resume Policies to DeltaFiles in an ERROR state
ResumePolicyDryRun	Resume Policies	Preview which DeltaFiles a policy would affect
ResumePolicyCreate	Resume Policies	Create Resume Policies
ResumePolicyRead	Resume Policies	View Resume Policies
ResumePolicyUpdate	Resume Policies	Edit Resume Policies
ResumePolicyDelete	Resume Policies	Delete Resume Policies

Note: The Admin Permission is a catch-all Permission that will allow access to everything in the system. This should be used with caution.

Roles

Roles include one or more Permissions and can be assigned to one or more Users.

Default Roles

DeltaFi includes three default Roles.

• Admin - This role includes the Admin Permission and allows access to everything in the system.
• Ingress Only - This role includes only the DeltaFileIngress Permission and should be assigned to non-person entity (NPE) accounts used only for sending data to the system.
• Read Only - This role includes only the Permissions needed to grant a "Read Only" experience to a User.

Creating Roles

1. Go to the Roles page in the UI.
2. Click on the Add Role button in the top right.
3. Enter the Name of the new Role.
4. In the Permissions section, select the Permissions you want to be assigned to the Role.

• Hovering over a Permission name will give a brief description of the Permission.

1. Click the Save button.

Assigning Roles to Users

1. Go to the Users page in the UI.
2. Find the User you want to modify and click the Edit button (pencil icon) in the right-most column.
3. In the Roles section, select the Role(s) you want to be assigned to the User.
4. Click the Save button.

Note: User RBAC information is cached for one minute. Changes could take that long to go into effect.

Entity Resolver

Note: The use of an Entity Resolver is an advanced topic and is not required for most DeltaFi instances.

DeltaFi supports the use of an Entity Resolver that allows Users to be identified by multiple entity identifiers (e.g. Distinguished Names). This method can be used to perform lookups in external authentication/authorization systems.

When an Entity Resolver is enabled in the DeltaFi system, on every request, the deltafi-auth service will call out to the Entity Resolver and provide the identifier for the User that made the initial request. The response should inform the deltafi-auth service of other entities by which the User should be identified. This response is cached, by default, for one minute.

Building an Entity Resolver

An Entity Resolver is a simple application that can be written in any programming language as long as it can be packaged as a Docker image.

Interface

An Entity Resolver interfaces with DeltaFi through HTTP POST requests made from DeltaFi to the Entity Resolver. By default, all requests will:

• Be made on port 8080 to the / endpoint.
• Have a Content-Type of application/json.
• Include a body that is a JSON array containing one element - the primary identifier of the User.
  • When running in Basic Authentication mode, this will be the username.
  • When running in Client Certificate Authentication mode, this will be the Distinguished Name (DN).

DeltaFi expects a response that is also a JSON array that includes all the identifiers by which the User should be identified.

For example, a request from DeltaFi to an Entity Resolver might look like this:

POST / HTTP/1.1
Host: 127.0.0.1:8080
Content-Length: 12
Content-Type: application/json

["CN=Alice"]

An example response might be:

[
  "CN=Alice",
  "CN=Sales Managers"
]

In this example, the Entity Resolver is telling the DeltaFi that the User with the DN CN=Alice should also be identified as a User with the DN CN=Sales Managers. This would allow a User to be created with the DN set to CN=Sales Managers. Any Roles granted to the Sales Managers User would be granted to Alice when she accessed the system.

Docker

When packaging an Entity Resolver in a Docker image, be sure to expose port 8080 in your Dockerfile.

EXPOSE 8080

Enabling an Entity Resolver

Once you have an Entity Resolver Docker image built, you can configure DeltaFi to use it by modifying the deltafi.auth.entityResolver section in your site.values.yaml file (as described in the Install DeltaFi Core section.)

deltafi:
  auth:
    mode: cert
    entityResolver:
      enabled: true
      image: your-entity-resolver-image:1.0.0

Then update DeltaFi with the new configuration.

deltafi update --values ~/site.values.yaml

Adding SSL Certificates to an Entity Resolver

You can configure DeltaFi to inject key and certificate files into the Entity Resolver using the same method used for plugins (see Plugins SSL Config for details).

After running the setup and restarting the Entity Resolver container, the application will have access to the following files:

• /certs/tls.key: The private key
• /certs/tls.crt: The certificate
• /certs/ca.crt: The CA certificate chain

Adding Config Files to an Entity Resolver

To add configuration files to an Entity Resolver add a config section under entityResolver in the site.values.yaml file. This section should include a map of filenames to their corresponding file contents. The mapped files will be placed in the /config directory inside the Entity Resolver container where they can be read by the application.

For example, if the Entity Resolver requires a configuration file called identifiers.yaml, your site.values.yaml would look like this:

deltafi:
  auth:
    mode: cert
    entityResolver:
      enabled: true
      image: your-entity-resolver-image:1.0.0
      config:
        identifiers.yaml:
          bob:
            - super
            - admin

The configuration file would be available at /config/identifiers.yaml.