External Systems
An external system is any code or program that can access data in Document Warehouse. In order for such a program to be able to do anything a user has to be created that is linked to that program. Some examples of “external systems” are: the e-platform, or D365-FO.
An external system could also generate authentications tokens that allow them to open the user interface in a browser such that the user does not need to authenticate again. (This is what happens when you click the “dino” icon in D365-FO.)
Just creating an “external system” is not enough. There should also be a link between an “Internal” user (= Document Warehouse user) and the external system. To do so, two pieces of information are required: 1) who is the “internal” user, and 2) to which user of the external system is this user linked.
This allows to link a single “internal” user to multiple external systems, and define for each of those systems what the ID of that user is.
An example to clarify:
Assume 3 different programs all have a user “Frederick”, and they define this user unique ID like this:
In D365-FO: frederick.grumieaux@9altitudes.com
In Business Central: user “23345”
In Active Directory: ADULTIMA\FREDERICKGM
These each are unique identifiers of the same user within those system, yet are different between those systems. So this means we need to know the unique ID of the user in that program, and map it to a known user (in this case the same user) in Document Warehouse.
An important remark: it is not possible to define multiple links from the same external system to the same internal user.
This will only result in a valid token if all of the following are true:
The external system id exists, and is not deactivated
The secret is one of the two valid secrets for the external system.
The provided user ID maps to a user linked to the external system.
The “internal” user is not deactivated
Important remark
Do not ever share the same external system between different programs. This will enventually lead to problems.
For example: it should always be possible to change the secrets without affecting any other applications.
About secrets
When creating an external system 2 secrets are provided: a primary secret, and an alternate secret.
The idea is that you should use the “primary” secret to authenticate. And store the alternate on another safe location.
Then if later one of the two keys are suspected to be compromised, it should be easy to change the key without any downtime. This is very important since a key basically is a password that access for many users. In this case:
Replace the “primary key” in the software with the original “alternate key”.
Click the “Renew secret” once (!) in the web site. A new secret is created and displayed. Write down this key.
In the software change the previous “alternate key”, with the newly generated key.
Click the “Renew secret” once (!) more in the web site. A new secret is created and displayed. Write down this key, and store it in another safe location.
After clicking the “Renew secret” button, the original “Primary secret” is voided, and the original “alternate secret” is promoted to be the new “primary secret”. The new key that is created is considered the new “alternate key”. This means that the original primary key can’t be used anymore to authenticate, but the original alternate key can still be used. That is also the reason why you should renew the key again immediately. This will repeat the process, and then both “old” keys are replaced with new keys. If done right there should be exactly 0 impact on the application itself; and the security thread should be resolved.
Creating an external system
Navigate to the configuration page
Select the “External Systems” tab.
Click the “+” button.
Click the “+” button.
Switch “public” to “Yes”
Click the “save” button.
A new system will now be created, and two secrets will be shown.
Write down those two keys and store them in a safe location. These are application keys, and you will see them only now (!)
Once you have created the system, you must add at least one user to the system.
Revoking user access via an external system
Select the external system in the list
Select the user from the list, in the external systems details pane
Click on the delete button just above the user list.
Note: revoking access this way still allows the user to log in using the web interface.
Recycling secrets
The “Renew secrets” button can be found in the configuration settings under tab “External Systems”.
Select the program for which the secret is compromised.
Click the “Renew secrets” button.
Make sure you know what you are doing!
Add a user to an external system
Steps:
Select the correct external system from the list
Click on the “+” somewhere in the middle of the right pane to add the user.
Enter the details of the new user in the two fields just above the table:
A field where you must enter the ID of the user as known by the external system.
A field where you can select an existing user
Save the changes using the “save” button.
Recycling secrets
Pre-requisite: make sure you know what you are doing!
The “Renew secrets” button can be found in the configuration settings under tab “External Systems”.
Select the program for which the secret is compromised.
Click the “Renew secrets” button.
Last updated
