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 further security and control over your environment, you can also apply your existing LDAP authentication, Access Control, and Migration Management configuration to the Data Migrator API and CLI using API Access Control.

info

Applying access control to Data Migrator API 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 access control to the Data Migrator API.

Limitations

• In this release, only the root admin user (initial UI admin user) can apply API LDAP access control configuration.
• In this release, API LDAP access control applies to the Data Migrator API only. Hivemigrator API LDAP access control will be available in later releases.
• In this release, the API Access Control LDAP config file /etc/wandisco/livedata-migrator/ldap.properties is not included in backups. See what a Data Migrator backup doesnt include for more info.

Apply access control to Data Migrator API

note

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.

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 API:

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 manually for changes to take effect.
   2. Choose Apply & Restart now to apply configuration to all instances and restart the Data Migrator service automatically.

tip

If there is no new config changes to push, selecting Apply & Restart now won't trigger an automatic restart of Data Migrator. Additionally, enabling or disabling Migration Management restarts the UI automatically and won't trigger an automatic restart of Data Migrator 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 livemigrator 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 livemigrator 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 livemigrator --host 127.0.0.1 --user admin0001 

Example connect command with user and tls options

connect livemigrator --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 livemigrator 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]"
}

API endpoint access

See below for a list of endpoints requiring the Admin or Migration Manager roles to access.

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

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.