Configure API LDAP access control

To manage authentication and access control for your Data Migrator UI, you can configure LDAP Authentication and Access Control. Additionally, API access can be secured by setting up basic authentication for the Data Migrator and Hivemigrator API.

For further security and control over your environment, you can also apply your existing LDAP authentication, Access Control, and Migration Management configuration to the APIs using API Access Control. Since the CLI makes calls to both APIs, applying API Access Control extends this additional security to CLI usage as well.

note

In this release, applying Migration Management configuration to the Hivemigrator API is not supported. See Limitations.

info

Applying access control to both APIs will deploy configuration to all available Data Migrator instances. If you have multiple instances that require individual disparate security configuration, contact Support.

Prerequisites

• Configure LDAP Authentication and Access Control.
• Configure basic authentication.
• If you're using Migration Management, enable Migration Management before applying API Access Control.

Limitations

• In this release, only the root admin user (the initial UI admin user) has the capability to initially apply API LDAP access control configuration. LDAP admin users can subsequently apply API access control after it has been initially applied by the root admin user.

info

Use your root admin user (initial UI admin user) when applying API Access Control for the first time. Initially, only the root admin user will have the basic auth credentials to communicate with the endpoint. LDAP Admin users can then apply API Access control after initially applying with your root admin user.

• For this release, while Migration Management for Hivemigrator is supported in the UI, you can't apply your Migration Management configuration to the Hivemigrator API/CLI. This will be supported in a future release.

Apply access control

note

Ensure you complete the prerequisites including basic authentication for Data Migrator and Hivemigrator before attempting to apply API access control.

tip

Enabling API Access Control will create an ldap.properties file holding LDAP configuration and is updated when you select Apply and Restart now or Apply and Restart later. The security.type property will be automatically set to ldap regardless of what it was previously set to in /etc/wandisco/livedata-migrator/application.properties.

To apply your existing LDAP authentication, Access Control, and Migration Management configuration to the Data Migrator and Hivemigrator APIs:

1. Sign in to the UI with your registered admin user account.
2. Select the settings cog to go to the Settings page.
3. Select API Access Control from the submenu.
4. Select either Apply & Restart later or Apply & Restart now.
   1. Choose Apply & Restart later to apply configuration to all instances. You must restart the Data Migrator service and Hivemigrator service manually for changes to take effect.
   2. Choose Apply & Restart now to apply configuration to all instances and restart the Data Migrator and Hivemigrator services automatically.

tip

Selecting Apply & Restart later requires a manual restart of services. If you subsequently select Apply & Restart now with no new changes, services will not restart automatically. Additionally, enabling or disabling Migration Management restarts the UI automatically and won't trigger an automatic restart when you select Apply and Restart now.

caution

After applying access control to the API, if you make changes to LDAP Authentication, Access Control, or Migration Management, you must apply these new changes to the API with Apply and Restart now or Apply and Restart later in API Access Control.

CLI access

When accessing the CLI with API Access Control applied, use the connect command with the required --user option to supply a username and authenticate as a specific user. Once authenticated, the CLI will use an authentication token for all subsequent operations. If another user needs to authenticate in the same session, run the connect command with the --user option to authenticate as a new user.

See the connect CLI command for more information and additional options.

Examples

Example connect command with user option

connect --host 127.0.0.1 --user admin0001 

Example connect command with user and tls options

connect --host 127.0.0.1 --user admin0001 --ssl

note

If Data Migrator is restarted or the JWT token keys are rotated, any operations requiring authentication will fail, and you'll need to authenticate again with the connect command.

tip

When logged-in as a non-admin user, depending on the user's authorization level, restricted operations return error responses showing the user's role.

Example:

Example CLI error message

{
  "error" : 16001,
  "status" : 403,
  "title" : "Access Denied.",
  "message" : "User does not have sufficient authority. Provided user role is [ROLE_MIGRATION_MANAGER]"
}

Re-authentication on restart behaviour

Restarting the services results in the revocation of authentication tokens.

If you are logged in and authenticated during a restart and attempt an action in the UI, an initial authentication failure will occur. However, the UI will then re-authenticate using the same credentials and continue functioning as expected.

If you're currently using the CLI, and services are restarted or the JWT token keys are rotated, any operations requiring authentication will fail, and you'll need to authenticate again with the connect command.

API endpoint access

See below for a list of endpoints requiring Admin or Migration Manager roles. Note that Admin has access to all endpoints, while Migration Manager access is limited to endpoints specified.

Data Migrator API

Admin role required

The following endpoints require the Admin role.

Method	Endpoint
Filesystem endpoints
PATCH/POST	/fs/sources/adls2/oauth2/{fileSystemId}
PATCH/POST	/fs/sources/adls2/shared-key/{fileSystemId}
PATCH/POST	/fs/sources/hdfs/{fileSystemId}
PATCH/POST	/fs/targets/hdfs/{fileSystemId}
..	..

note

All source and target filesystem endpoints require the Admin role although not explicitly listed here.

Method	Endpoint
Backup controller
POST	/backups
PUT	/backups/config/schedule
POST	/backups/restore/{backupName}
Bandwidth controller
DELETE	/bandwidthPolicies/application
POST	/bandwidthPolicies/application
DELETE	/bandwidthPolicies/dataAgents/{agentName}
POST	/bandwidthPolicies/dataAgents/{agentName}
Configuration controller
PUT	/configuration/property
PUT	/configuration/ldap/
PUT	/configuration/ldap/disable
DELETE	/configuration/managementGroups
POST	/configuration/managementGroups
PUT	/configuration/managementGroups
PUT	/configuration/managementGroups/enable
PUT	/configuration/managementGroups/disable
Consumption controller
PUT	/consumption/switchToConsumption
PUT	/consumption/extendTime
DTA Controller
DELETE	/scaling/dataagents/{agentName}
POST	/scaling/dataagents/
Filesystem controller
POST	/fs/{role}/{fsId}/writeFile
POST	/fs/{role}/{fsId}/moveByPath
POST	/fs/{role}/{fsId}/mkdir
POST	/fs/{role}/{fsId}/deleteByPath
POST	/fs/{role}/{fsId}/createFile
GET	/fs/{role}/{fsId}/readFile
GET	/fs/{role}/{fsId}/pathExists
GET	/fs/{role}/{fsId}/fileSystemURI
License controller
POST	/license
Metering controller
PUT	/metering
Migration controller
DELETE	/migrations
Email notifications controller
PUT	/notifications/config/email
PUT	/notifications/config/email/registration
POST	/notifications/config/email/test
Source filesystem controller
DELETE	/fs/sources
DELETE	/fs/sources/{sourceId}
Target filesystem controller
DELETE	/fs/targets/{targetId}
DELETE	/fs/targets
Threads controller
GET	/threads
GET	/threads/states

Migration manager role required

The following endpoints require the Migration Manager role.

Method	Endpoint
Exclusions controller
PUT	/exclusions/regex/{id}
PUT	/exclusions/fileSize/{id}
PUT	/exclusions/date/{id}
PUT	/exclusions/age/{id}
DELETE	/exclusions/{exclusionId}
Filesystem controller
GET	/fs/{role}/{fsId}/listPaths
Migration Gate controller
PUT	/gates/gate
POST	/gates/gate/bulk/delete
DELETE	/gates/gate/deleteAll
PUT	/gates/gate/close
Migration controller
POST	/migrations/{migrationId}/start
POST	/migrations/{migrationId}/stop
POST	/migrations/{migrationId}/resume
POST	/migrations/{migrationId}/reset
POST	/migrations/{migrationId}/addPendingRegion
POST	/migrations/stop
PUT	/migrations/{migrationId}/maxStoppedUnscheduledEventBuffer/{maxEvents}
PUT	/migrations/{migrationId}/maxPendingRegions/{maxPendingRegions}
DELETE	/migrations/{migrationId}/exclusions/{exclusionId}
PUT	/migrations/{migrationId}/exclusions/{exclusionId}
DELETE	/migrations/{migrationId}
PATCH	/migrations/{migrationId}
PUT	/migrations/{migrationId}
Path mapping controller
PUT	/transformations/mappings
DELETE	/transformations/mappings/{id}
Requeuing actions controller
POST	/requeuing-actions/queuing/{migrationId}/{actionId}/cancel
Verification controller
PUT	/verifications
DELETE	/verifications/{verificationId}
POST	/verifications/{verificationId}/cancel

Hivemigrator API

Admin role required

The following endpoints require the Admin role.

Method	Endpoint
Agent Api Controller
POST	/agent/check-remote-connection
POST	/agents
DELETE, POST, PUT	/agents/{name}
POST	/agents/{name}/certificates/generate
POST	/agents/{name}/certificates/upload
POST	/agents/{name}/check
POST	/agents/{name}/deploy
POST	/agents/{name}/validate-config
Agent Rate Limits Api Controller
POST	/agents/{name}/rate-limits
Authentication Api Controller
PUT	/authentication/logoutAll
Backup Api Controller
POST	/backups
POST	/backups/restore/{name}
PUT	/backups/schedule
Config Api Controller
POST	/config
POST	/config/certificates/generate
POST	/config/certificates/upload
PUT	/config/ldap/disable
PUT	/config/ldm

Migration manager role required

The following endpoints require the Migration Manager role.

Method	Endpoint
Migration Api Controller
POST	/migration
POST	/migration/pause
POST	/migration/pause/all
POST	/migration/reset
POST	/migration/reset/all
POST	/migration/resume
POST	/migration/resume/all
POST	/migration/start
POST	/migration/start/all
POST	/migration/stop
POST	/migration/stop/all
DELETE	/migration/{name}
Rules Api Controller
POST	/rule
DELETE, PUT	/rule/{name}

Swagger API reference

When accessing the Swagger API reference interface with API access control applied, and no authorization information supplied, all endpoints are visible but only read-only endpoints are accessible.

You can authorize with your basic auth credentials or with a JSON Web Token (JWT) on the Swagger API reference interface.

Any LDAP user can be authorized to use the Swagger API reference and perform the actions configured in the role based access control. Root admin users authorize with their basic auth credentials, only LDAP users are authorized using JSON Web Token (JWT).

Authorize with basic auth credentials

1. From the Swagger API reference interface, select Authorize.
2. Under basicAuth, enter your admin user username and password.
3. Select Authorize.
4. Select Close.

You'll now be authorised to access the Swagger API reference interface commands.

Authorize with JSON Web Token (JWT)

1. Get a JWT token for a user from the Authentication Controller endpoint /authentication/authenticate. Example using the Swagger API reference interface:
   1. Navigate to Authentication Controller endpoint /authentication/authenticate.
   2. In the User login credentials provide your LDAP username and password.
   3. Execute the command.
   4. Copy the JWT token (idToken) from the response without quotation characters.
2. From the Swagger API reference interface, select Authorize.
3. Under bearerAuth, enter the token in the Value field.
4. Select Authorize.

You'll now be authorised to access the relevant Swagger API reference interface commands as per your LDAP/RBAC settings.

Once an authorization is set, it remains in force until you select Authorize and Logout under Available authorizations.