Skip to main content

Manage who has access to the Management API

IP Whitelist​

In order to protect the Xillio Link Redirector's Management API, it is recommended to setup firewall rules to block unknown IP-addresses from accessing the specific port at which the API is running. Configuring these rules are highly dependent on the system where the Xillio Link Redirector is running. Therefore, this is left as an exercise to the user.

Note: Make sure that you apply these firewall rules only to the ports of the Management API.

Some additional information can be found here:

User management​

Another way of limiting access to the Management API is using the built-in authentication features. Continue reading for information on the available methods.

User Roles​

Users that interact with the Xillio Link Redirector are split into four different roles; anonymous, user, manager and admin.

RoleRedirectingMigrationsRules
anonymous✅ Yes❌ No❌ No
user✅ Yes🔎 Read-only🔎 Read-only
manager✅ Yes✅ Yes🔎 Read-only
admin✅ Yes✅ Yes✅ Yes

Anonymous users are the ones using the redirecting logic of the application. They have no access to the management API whatshowever. All other three roles have access to the management API although limited per role. The specific access can be seen in the table above.

Configuring these roles depends on the authentication mechanism that is selected in the configuration. For each of these mechanisms you can find more information below.

Basic Authentication through HTPasswd​

You can enable Basic Authentication by adding the following to your configuration file:

# config.yaml
authentication:
    type: password
    file: ./.htpasswd
    roles:                 # Optionally you can add roles that will applied to all users
      - admin              # that are loaded from this file

By setting the type to password we will tell the API that we will be using basic auth using Apache .htpasswd Password Format.

Note: For security reasons the MD5 and SHA hashing algorithms have been disabled. These hashing algorithms are deemed outdated and unsafe. Currently, the BCrypt hashing algorithm is implemented, which is a much stronger alternative to the previous ones.

The file entry in the configuration will tell the Xillio Link Redirector where to look for the user information. The roles can optionally be added to only give certain roles to the loaded users.

The file that is referenced by the file-directive should be created with the htpasswd tool from Apache. For more information on how to use the htpasswd tool, see the manual from Apache.

To create a .htpasswd file, the following command can be run:

htpasswd -cB .htpasswd admin

You will be prompted to enter a password and repeat it. When completed, a file called .htpasswd should be created. Opening this file should show something that looks like admin:$2y$.......... This is the username + hashed password that was just created.

In the command that was just executed the flags -cB were used. The c flag means 'create a new file' and the B flag instructs the tool to use BCrypt, as mentioned earlier.

When adding more users, be sure to remove the c-flag, to avoid overwriting the existing file. For example:

htpasswd -B .htpasswd another-user

OpenID Connect​

The Xillio Link Redirector supports Identity and Access Management tools such as Auth0 or Keycloak. All that is needed is the OpenID Endpoint Configuration and some minor tweaks to the Xillio Link Redirector configuration.

Keycloak's Endpoint Configuration​

The OpenID Endpoint Configuration in Keycloak can be found at Realm Settings > General > OpenID Endpoint Configuration.

Setting the configuration​

Inside the config.yml of the Xillio Link Redirector the following section should be added:

# config.yaml
authentication:
    type: openid
    file: https://{link-to-IAM-software}/.well-known/openid-configuration

The authentication.file field should point to the URL that was collected in the sections above.

Additionally, it is possible to set authentication.file to a file location such as file://../openid.json. This will load the configuration from the local system. One possible use-case for this would be when the Xillio Link Redirector is air-gapped.

Once the configuration is applied, the Xillio Link Redirector needs to be restarted. Requests to the management API are now protected and require the Authorization-Header to be set for each request. This header should start with Bearer followed by the JSON Web Token (JWT) that was generated by the IAM software.

For more information on how to get a token for KeyCloak click here.

Mutual TLS​

Mutual TLS (Transport Layer Security) ensures secure communication between two parties by requiring both parties to present a valid certificate to each other before they can communicate. This allows both parties to verify the identity of each other in order to establish a secure channel for communication.

In the context of API access, mutual TLS can be used to restrict access to an application by requiring clients to present a valid certificate. This ensures that only authorized clients can access the API.

The follow steps describe a generic way of implementing `mutual TLS in the Xillio Link Redirector:

  1. Create a folder called certs in the root folder of your project. We will use this folder to store all the certificates needed.

  2. Collect your server certificate and key. These certificates will be used to identify the server to the clients. Store the certificate and key as certs/server.crt and certs/server.key, respectively. Any name for these files will do, but we use this filename as an example. The filenames are referenced to in the configuration file.

  3. Obtain or generate a root certificate authority (CA) certificate. This certificate will be used to sign the certificates of the clients. Store this certificate as certs/rootCA.crt.

  4. Generate a client certificate and key signed by the root CA. These certificates will be used to identify the client to the server. Store them as certs/client.crt and certs/client.key, respectively.

  5. Next, configure the server to require mutual TLS for API access. This is done by setting the following configuration fields:

api: 
    #... All configuration already present
    keyFile: certs/server.key
    certificateFile: certs/server.crt
    caFile: certs/rootCA.crt

  1. The Xillio Link Redirector can now be started and should work like it normally would. However, the Management API now requires a valid client certificate. Making a request to the Ping Endpoint should result in a invalid_certificate error.

  2. Configure the client to present their client certificate when accessing the API. This typically involves specifying the location of the client certificate and the root CA certificate. When using cURL you need to specify the --cert and --key flags, for example:

curl -k --cert client.crt --key client.key https://localhost:8443/xlr/api/system/ping

The -k option is only necessary when using self-signed certificates.

Mutual TLS is also available for using the proxy

It is possible to enable mutual TLS for the proxy in the same way you configure mutual TLS for the Management API. Just apply the steps above for the proxy options, instead of api in the example configuration.

Once mutual TLS is set up, clients will be required to present a valid client certificate in order to access the API. The server will verify the client's certificate before allowing the client to access the API. If the client's certificate is invalid, the server will deny access to the API.

It is important to ensure that the root CA certificate and the server and client certificates are properly secured and protected, as they contain sensitive information that could be used to compromise the security of the system.