From f3fff5ac5a11c9b314314f525b539396f2a0b0d0 Mon Sep 17 00:00:00 2001 From: Martijn Dirkse Date: Fri, 25 Oct 2024 16:32:39 +0200 Subject: [PATCH] Remove obsolete infor from administrator manual --- .../authorization/authorization.rst | 4 -- .../authorizationMethodsAndRoles.rst | 4 -- .../authorization/consoleAndLadybug.rst | 4 -- .../authorization/httpInterfaces.rst | 4 -- .../authorization/internalNetwork.rst | 4 -- .../authorization/secrets.rst | 4 -- .../MicrosoftEntraId/microsoftEntraId.rst | 6 ++- docs/source/deploying/credentials.rst | 2 +- docs/source/deploying/deploying.rst | 19 +++++++-- docs/source/deploying/dtapAndProperties.rst | 19 ++++----- .../deploying/overviewSecurityRoles.rst | 4 +- .../deploying/requiringAuthorization.rst | 42 +++++++++++++++++++ docs/source/operator/database.rst | 2 +- docs/source/operator/managing.rst | 4 +- docs/source/operator/uploading.rst | 2 +- 15 files changed, 75 insertions(+), 49 deletions(-) create mode 100644 docs/source/deploying/requiringAuthorization.rst diff --git a/docs/source/advancedDevelopment/authorization/authorization.rst b/docs/source/advancedDevelopment/authorization/authorization.rst index 51a74a3a..8fb68240 100644 --- a/docs/source/advancedDevelopment/authorization/authorization.rst +++ b/docs/source/advancedDevelopment/authorization/authorization.rst @@ -1,7 +1,3 @@ - .. WARNING:: - - The information given here is not complete. Please check :ref:`deploymentSecurity` for additional information. - .. _advancedDevelopmentAuthorization: Authorization diff --git a/docs/source/advancedDevelopment/authorization/authorizationMethodsAndRoles.rst b/docs/source/advancedDevelopment/authorization/authorizationMethodsAndRoles.rst index 609c62af..f91cb672 100644 --- a/docs/source/advancedDevelopment/authorization/authorizationMethodsAndRoles.rst +++ b/docs/source/advancedDevelopment/authorization/authorizationMethodsAndRoles.rst @@ -1,7 +1,3 @@ - .. WARNING:: - - The information given here is not complete. Please check :ref:`deploymentSecurity` for additional information. - .. _advancedDevelopmentAuthorizationMethodsAndRoles: Authorization methods and roles diff --git a/docs/source/advancedDevelopment/authorization/consoleAndLadybug.rst b/docs/source/advancedDevelopment/authorization/consoleAndLadybug.rst index 1ecc7b5f..ca8eff11 100644 --- a/docs/source/advancedDevelopment/authorization/consoleAndLadybug.rst +++ b/docs/source/advancedDevelopment/authorization/consoleAndLadybug.rst @@ -1,7 +1,3 @@ - .. WARNING:: - - The information given here is not complete. Please check :ref:`deploymentSecurity` for additional information. - .. _advancedDevelopmentAuthorizationConsoleLadybug: Interfaces Frank!Console and Ladybug diff --git a/docs/source/advancedDevelopment/authorization/httpInterfaces.rst b/docs/source/advancedDevelopment/authorization/httpInterfaces.rst index 11711d30..1ffa1785 100644 --- a/docs/source/advancedDevelopment/authorization/httpInterfaces.rst +++ b/docs/source/advancedDevelopment/authorization/httpInterfaces.rst @@ -1,7 +1,3 @@ - .. WARNING:: - - The information given here is not complete. Please check :ref:`deploymentSecurity` for additional information. - .. _advancedDevelopmentAuthorizationHttpInterfaces: HTTP Interfaces diff --git a/docs/source/advancedDevelopment/authorization/internalNetwork.rst b/docs/source/advancedDevelopment/authorization/internalNetwork.rst index 4b3a5d74..1a1c7608 100644 --- a/docs/source/advancedDevelopment/authorization/internalNetwork.rst +++ b/docs/source/advancedDevelopment/authorization/internalNetwork.rst @@ -1,7 +1,3 @@ - .. WARNING:: - - The information given here is not complete. Please check :ref:`deploymentSecurity` for additional information. - .. _advancedDevelopmentAuthorizationInternalNetwork: Restricting server to internal network diff --git a/docs/source/advancedDevelopment/authorization/secrets.rst b/docs/source/advancedDevelopment/authorization/secrets.rst index 6132f94d..fd39ce58 100644 --- a/docs/source/advancedDevelopment/authorization/secrets.rst +++ b/docs/source/advancedDevelopment/authorization/secrets.rst @@ -1,7 +1,3 @@ - .. WARNING:: - - The information given here is not complete. Please check :ref:`deploymentSecurity` for additional information. - .. _advancedDevelopmentAuthorizationSecrets: Credentials diff --git a/docs/source/deploying/IdentityProviders/MicrosoftEntraId/microsoftEntraId.rst b/docs/source/deploying/IdentityProviders/MicrosoftEntraId/microsoftEntraId.rst index bd493af7..6cb28450 100644 --- a/docs/source/deploying/IdentityProviders/MicrosoftEntraId/microsoftEntraId.rst +++ b/docs/source/deploying/IdentityProviders/MicrosoftEntraId/microsoftEntraId.rst @@ -1,6 +1,8 @@ -.. _deploymentMicrosoftEntraId: + .. WARNING:: + + This page is still work in progress. -THIS PAGE IS STILL WORK IN PROGRESS +.. _deploymentMicrosoftEntraId: Register application with identity provider Microsoft Entra ID ============================================================== diff --git a/docs/source/deploying/credentials.rst b/docs/source/deploying/credentials.rst index 116ed272..d70c8932 100644 --- a/docs/source/deploying/credentials.rst +++ b/docs/source/deploying/credentials.rst @@ -1,7 +1,7 @@ .. _deploymentCredentials: Credentials ------------ +=========== Frank configurations can communicate with external systems. These external systems may require credentials like usernames and passwords. The Frank!Framework needs to know these credentials. It is your job to configure these credentials, because they should not be included in Frank configurations. This section explains how you can do this. diff --git a/docs/source/deploying/deploying.rst b/docs/source/deploying/deploying.rst index e8f96bf8..f1ccb1b7 100644 --- a/docs/source/deploying/deploying.rst +++ b/docs/source/deploying/deploying.rst @@ -3,11 +3,23 @@ Administrator Manual ==================== -The Frank!Framework is a solution to quickly build enterprise applications, called Franks. A Frank consists of the Frank!Framework that is combined with Frank configurations. Frank configurations configure the Frank!Framework to provide the services you need. They are written as XML documents and property files. The chapters :ref:`gettingStarted` and :ref:`advancedDevelopment` explain how to write Frank configurations. This chapter can be studied independently from :ref:`gettingStarted`. It is not about writing Frank configurations, but focuses on deployment. How can a given Frank configuration be deployed on the IT infrastructure you want? +The Frank!Framework is a solution to quickly build enterprise applications, called Franks. A Frank consists of the Frank!Framework that is combined with Frank configurations. Frank configurations configure the Frank!Framework to provide the services you need. They are written as XML documents and property files. The chapters :ref:`gettingStarted` and :ref:`advancedDevelopment` explain how to write Frank configurations. This chapter can be studied independently from :ref:`gettingStarted`. It is not about writing Frank configurations, but focuses on deployment. How can a given Frank configuration or Frank application be deployed on the IT infrastructure you want? -The Frank!Framework is a Java web application that has to be served by an application server. The Frank!Framework can be deployed on many types of application servers, for example Apache Tomcat, JBoss Application Server (recently renamed to WildFly) or WebSphere Application Server. These application server types require different procedures for deploying the Frank!Framework. The present version of this manual only covers deployment on Apache Tomcat. If you want to deploy on a different type of application server, please seek info from one of the Frank!Framework maintainers. +The Frank!Framework is a Java web application that has to be served by an application server. The Frank!Framework can be deployed on many types of application servers, for example Apache Tomcat, WildFly or WebSphere Application Server. When you receive a Frank configuration or Frank application that has to be deployed, you usually have to do some additional configurations. The following should be considered: -The end of this chapter turns to the Frank!Framework. You learn how to configure the Frank!Framework by setting the DTAP stage (Development, Test, Acceptance, Production) and you learn how to set properties in general. Then you learn how to restrict access to the Frank!Console to protect your data and the privacy of your customers. Finally, you learn how to provide credentials of external systems to your Frank. +* The DTAP stage (Development, Test, Acceptance, Production) and property ``instance.name``. +* Configuring databases and queues. +* Configuring users, passwords and roles. +* Providing credentials for the Frank!Framework that it needs to contact third-party applications. +* The way Frank configurations can be found (already handled in a Docker image provided by Frank developers). + +.. WARNING:: + + The information in this chapter is not complete yet. Not all subject listed here are covered yet. + +This manual does not explain how to use an application server. Instead, it explains how to do the configurations listed above. The maintainers of the Frank!Framework have created a Docker image that holds the Frank!Framework deployed on Apache Tomcat, see https://github.com/frankframework/frankframework/blob/master/Docker.md. Frank developers can derive their image from this image to add Frank configurations. + +When you get a Docker image from Frank developers, you can trust that Apache Tomcat has been properly configured. In addition, the Frank!Framework should be able to find the configurations without any additional configurations. It remains your responsibility to take care of the other configurations explained in this chapter. Here is the table of contents of this chapter: @@ -15,6 +27,7 @@ Here is the table of contents of this chapter: :maxdepth: 3 dtapAndProperties + requiringAuthorization overviewSecurityRoles credentials IdentityProviders/MicrosoftEntraId/microsoftEntraId diff --git a/docs/source/deploying/dtapAndProperties.rst b/docs/source/deploying/dtapAndProperties.rst index 5df66cee..c1902a06 100644 --- a/docs/source/deploying/dtapAndProperties.rst +++ b/docs/source/deploying/dtapAndProperties.rst @@ -1,17 +1,12 @@ -.. _deploymentDtapAndProperties: +.. _deploymentDtapAndInstance: -The DTAP stage and setting properties -------------------------------------- +The instance name and the DTAP stage +==================================== -In the previous sections :ref:`deploymentTomcat4Frank` and :ref:`deploymentTomcat`, you learned how to get the Frank!Framework running. This section and the next are about fine-tuning the Frank!Framework. The details of your application server are not so important anymore; you can read this section without understanding the previous. +This section describes two basic properties you have to set as a system administrator: ``instance.name`` and ``dtap.stage``. Property ``instance.name`` is a name for the set of configurations that is hosted on a single server or on a group of servers running in parallel. The Frank!Framework uses this name in many ways, so it is important that you provide it. -As a system administrator, you should understand the life cycle of a Frank config. During this life cycle, a Frank is deployed on different instances of the Frank!Framework. During its development, the config lives on the development environment (D). When the developers consider releasing, they bring their work to another instance of the Frank!Framework, the test environment (T). When the tests are successful, the Frank config is released to the customer. The customer should do acceptance tests on a dedicate Frank!Framework instance (A). Only after acceptance testing succeeds, the work should go to production (P). These four letters form the famous DTAP acronym. The Frank!Framework uses an extra (fifth) stage: the letter, L, the local development computer of a single developer. +Property ``dtap.stage`` is about the life cycle of a Frank config. During this life cycle, a Frank is typically deployed on different servers (or server groups). During its development, the config lives on the development environment (D). When the developers consider releasing, they bring their work to another environment, the test environment (T). When the tests are successful, the Frank config is released to the customer. The customer should do acceptance tests on a dedicate environment (A). Only after acceptance testing succeeds, the work should go to production (P). These four letters form the famous DTAP acronym. The Frank!Framework uses an extra (fifth) stage: ``LOC``, the local development computer of a single developer. Please note that ``instance.name`` is usually the same for each DTAP stage. -As a system administrator, you have to set the DTAP stage by setting the system property ``dtap.stage``. You already did this in section :ref:`deploymentTomcat`. The allowed values are ``LOC``, ``DEV``, ``TST``, ``ACC`` and ``PRD``. If you use the Frank!Runner, you get DTAP stage "LOC" by default. +As a system administrator, you have to set the DTAP stage by setting the system property ``dtap.stage``. The allowed values are ``LOC``, ``DEV``, ``TST``, ``ACC`` and ``PRD``. -Remember that there are two methods to set system properties when you are using Apache Tomcat: - -#. You can set Java properties with the command line that starts Apache Tomcat or the Frank!Runner. You use command-line arguments like ``-D=``, for example ``-Ddtap.stage=ACC``. If you have spaces in your value, add quotes. -#. You can add properties to the text file ``/conf/catalina.properties``. - -There are many more properties than "dtap.stage" that have impact on the Frank!Framework, but you do not have to know much about them. Frank!Developers are responsible for setting them. They can configure different properties for different DTAP stages, allowing them to do a lot of fine-tuning for you already. Occasionally, a Frank developer may ask you to set a property when you are cooperating to fix an issue. The Frank developer should understand the impact in this case. +Frank developers can make their application dependent on the DTAP stage. This may help you to configure different databases and different queues for each DTAP stage. Please contact the developer of the Frank application for more information. \ No newline at end of file diff --git a/docs/source/deploying/overviewSecurityRoles.rst b/docs/source/deploying/overviewSecurityRoles.rst index d9955267..279d3e19 100644 --- a/docs/source/deploying/overviewSecurityRoles.rst +++ b/docs/source/deploying/overviewSecurityRoles.rst @@ -3,7 +3,7 @@ Overview of security roles ========================== -With the tutorial of the previous page, you learned how security is configured. Now we explain what options you have to restrict access to the Frank!Console. Your options follow from the roles that are defined within the Frank!Framework. See the following list: +Here are the security roles known by the Frank!Framework: IbisWebService Can call an Ibis WebserviceListener. @@ -23,5 +23,3 @@ IbisTester .. NOTE:: "What is 'Ibis'?", you might ask. This comes from the time before the frankemwork was renamed to Frank!Framework. In that time, the brands "Ibis" and "Ibis Adapter Framework" were used. These names have not all been replaced by their Frank! equivalents. - -You can assign these roles to users, as you did when you edited ``tomcat-users.xml``. You assign a value to the ``roles`` attribute that is a comma-separated list of roles. Each role should be taken from the list. diff --git a/docs/source/deploying/requiringAuthorization.rst b/docs/source/deploying/requiringAuthorization.rst new file mode 100644 index 00000000..e08728b6 --- /dev/null +++ b/docs/source/deploying/requiringAuthorization.rst @@ -0,0 +1,42 @@ +.. _deployingRequiringAuthorization: + +Requiring authorization +======================= + +If you work with a Docker image, authorization should have been cared for. Otherwise you may need the information in :ref:`advancedDevelopmentAuthorization`. That section explains authorization to Frank developers. + +.. WARNING:: + + Application servers provide mechanisms outside the Frank!Framework to require authorization. The Frank!Framework has been developed to run on multiple brands of application servers. Therefore the Frank!Framework has its own mechanisms. It is recommended to use these and it is deprecated to use the authorization options of the applciation server. + +This section assumes that authorization has been set up for you. Frank developers can choose the used authorization mechanism. The subsections below explain for each mechanism how you should configure users, passwords and roles. + +YAML authorization +------------------ + +This mechanism expects that users, passwords and roles are in a YAML file that you provide. If you use a Docker image derived from the Frank!Framework on Tomcat Docker image, then the file is expected at ``opt/frank/resources/localUsers.yml``. Here is an example: + +.. code-block:: none + + users: + - username: joe + password: myPassword + roles: IbisWebService,IbisObserver + +This file says that user ``joe`` has the roles ``IbisWebService`` and ``IbisObserver``. The roles known by the Frank!Framework are listed in the next section :ref:`deploymentOverviewSecurityRoles`. When there are multiple roles they have to be separated by a comma. + +Active Directory +---------------- + +With this authorization mechanism, you are responsible for configuring users, password and Active Directory roles. The Frank!Framework needs a role mapping file, a file that translates Active Directory roles to the Frank!Framework roles. Here is an example: + +.. code-block:: none + + IbisTester=xxx,yyy + IbisAdmin=zzz + +This example assumes that ``xxx``, ``yyy`` and ``zzz`` are LDAP roles. To the left of the ``=`` sign is the Frank!Framework role corresponding to the Active Directory roles. + +.. NOTE:: + + Information about the other authorization mechanisms supported by the Frank!Framework is not available yet. \ No newline at end of file diff --git a/docs/source/operator/database.rst b/docs/source/operator/database.rst index 8b8a3f17..bbeae226 100644 --- a/docs/source/operator/database.rst +++ b/docs/source/operator/database.rst @@ -47,4 +47,4 @@ You learned how to view data. When you want to insert or update records, you hav .. WARNING:: - In production, you are strongly discouraged to modify your data this way. Maintaining the data should be the responsibility of the Frank configs you deployed. A wise system administrator should configure security such that only authorized operators can use this page of the Frank!Framework. For more information, see :ref:`deploymentSecurity`. \ No newline at end of file + In production, you are strongly discouraged to modify your data this way. Maintaining the data should be the responsibility of the Frank configs you deployed. A wise system administrator should configure security such that only authorized operators can use this page of the Frank!Framework. For more information, see :ref:`deploying`. \ No newline at end of file diff --git a/docs/source/operator/managing.rst b/docs/source/operator/managing.rst index 7802b571..cfe9e2ca 100644 --- a/docs/source/operator/managing.rst +++ b/docs/source/operator/managing.rst @@ -5,7 +5,7 @@ Management ========== -In the preceeding sections, you have learned how to monitor the status of the Frank!Framework and how to investigate issues. In this section you will start learning what you can do as a site owner. This section is about temporarily stopping adapters and receivers. The next section :ref:`frankConsoleConfigsUploading` is about uploading new versions of a Frank config. If you are also a system administrator, you also need to read chapter :ref:`deploying`, in particular subsections :ref:`deploymentDtapAndProperties` and :ref:`deploymentSecurity`. +In the preceeding sections, you have learned how to monitor the status of the Frank!Framework and how to investigate issues. In this section you will start learning what you can do as a site owner. This section is about temporarily stopping adapters and receivers. The next section :ref:`frankConsoleConfigsUploading` is about uploading new versions of a Frank config. If you are also a system administrator, you also need to read chapter :ref:`deploying`. In this chapter, you continue learning about :ref:`frankConsoleScheduling` a task for periodic execution. The final section :ref:`operatorManagingProcessedMessages` is also important; you learn about auditing and about fixing messages for which processing has failed. Finally, section :ref:`frankConsoleDiskUsage` gives you some tricks to reduce the amount of data stored by the Frank!Framework. @@ -141,7 +141,7 @@ The Test Pipeline screen allows you to pass messages directly into adapters, byp .. WARNING:: - Wise system administrators should prevent unauthorized users from accessing the Test Pipeline page. Using this feature in your production environment is strongly discouraged, because the receivers you bypass perform important tasks. In the example above, input file ``work\input\example2.csv`` might be processed again if the receiver would start again. See also :ref:`deploymentSecurity`. + Wise system administrators should prevent unauthorized users from accessing the Test Pipeline page. Using this feature in your production environment is strongly discouraged, because the receivers you bypass perform important tasks. In the example above, input file ``work\input\example2.csv`` might be processed again if the receiver would start again. See also :ref:`deploying`. 27. Please restart receiver "receiverGetDestinations" like explained. In the next section, you may want to have all adapters and receivers in state Started. diff --git a/docs/source/operator/uploading.rst b/docs/source/operator/uploading.rst index f4b6e4a5..afbf2500 100644 --- a/docs/source/operator/uploading.rst +++ b/docs/source/operator/uploading.rst @@ -44,7 +44,7 @@ In the next subsection, you will use the previous version of the NewHorizons con .. WARNING:: - You see how powerful the JDBC | Execute Query page is? You really need security on your production site, see section :ref:`deploymentSecurity`. + You see how powerful the JDBC | Execute Query page is? You really need security on your production site, see section :ref:`deploying`. #. Stop the Frank!Framework. #. Delete all files from ``work\input``, ``work\processing``, ``work\processed``, ``work\error``, but not the directories themselves.