Skip to content

Latest commit

 

History

History
555 lines (400 loc) · 32.4 KB

InstallationAndAdministrationGuide.rst

File metadata and controls

555 lines (400 loc) · 32.4 KB
Raw

Installation and Administration Guide

This guide provides the procedure to install the AuthzForce server, including system requirements and troubleshooting instructions.

Installation via Docker (container image)

See docker/README.md on Github.

Manual installation via tar.gz

System requirements:

  • CPU frequency: 2.6 GHz min

  • CPU architecture: i686/x86_64

  • RAM: 4GB min

  • Disk space: 10 GB min

  • File system: ext4

  • Operating System: Ubuntu 20.04 or later

  • Java environment:

    • JRE 17 LTS either from OpenJDK or Oracle;
    • Tomcat 10.x or later.

See tar/README.md on Github.

Installation via APT (Ubuntu .deb package)

System Requirements

The system requirements are the following:

  • CPU frequency: 2.6 GHz min

  • CPU architecture: i686/x86_64

  • RAM: 4GB min

  • Disk space: 10 GB min

  • File system: ext4

  • Operating System: Ubuntu 23.04 or later (Tomcat 10 package not available yet on latest LTS)

  • Java environment:

    • JRE 17 LTS either from OpenJDK or Oracle;
    • Tomcat 10.x or later.

Installation

If you are already using an older version of AuthzForce and wish to migrate your setup to the new version, please backup the folder /opt/authzforce-ce-server first because it will be overwritten by the new version, then proceed with the Minimal setup below, to install the new version; finally, proceed with the Upgrade section that follows, to transfer data from the old version.

Minimal setup

  1. Install a JRE 17 LTS if you don't have one already, using either of these two methods depending on your JDK preference:

    • For OpenJDK: $ sudo apt install openjdk-17-jre

  2. Install Tomcat 10 (Ubuntu 23.04 or later): $ sudo apt install tomcat10.

  3. Each AuthzForce Server version number has the form MAJOR.MINOR.PATH (Semantic Versioning). Identify the latest binary (Ubuntu package with .deb extension) release of AuthzForce Server on Maven Central Repository that matches the MAJOR.MINOR version of this documentation. This is the current latest software version to which this documentation version applies. If you want to use a different software version, go to the latest documentation version with matching MAJOR.MINOR and follow instructions there. Else you may download the software version. We will refer to its version number as M.m.P (please replace accordingly):

    $ wget https://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-server-dist/M.m.P/authzforce-ce-server-dist-M.m.P.deb

    You should get a file called authzforce-ce-server-dist-M.m.P.deb.

  4. Copy this file to the host where you want to install the software.

  5. On the host, from the directory where you copied this file, run the following commands:

    $ sudo apt install curl
$ sudo apt install ./authzforce-ce-server-dist-M.m.P.deb

  6. At the end, you will see a message giving optional instructions to go through. Please follow them as necessary.

Note that Tomcat default configuration may specify a very low value for the Java Xmx flag, causing the AuthzForce webapp startup to fail. In that case, make sure Tomcat with Xmx at 1 Go or more (2 Go recommended). You can fix it as follows:

$ sudo sed -i "s/-Xmx128m/-Xmx1024m/" /etc/default/tomcat
$ sudo systemctl restart tomcat10

Known issue: lack of entropy may cause delays in Tomcat start up on virtual machines in particular: more info on Entropy Source issue. So beware.

Upgrade

If you are still using an older version of AuthzForce and wish to migrate your setup to the new version, assuming you made a backup in a separate location, as told previously, please follow these steps:

  1. Download AuthzForce server upgrader distribution (.tar.gz extension) from Maven Central Repository in the same version as the Server version you want to upgrade to. You get a file called authzforce-ce-server-upgrader-M.m.P.tar.gz (replace M.m.P with the corresponding version).

  2. Copy this file to the host where the old AuthzForce Server is installed, and unzip it and change directory:

    $ tar xvzf authzforce-ce-server-upgrader-M.m.P.tar.gz
$ cd authzforce-ce-server-upgrader-M.m.P

  3. Follow the instructions in file README.html.

Advanced setup

The Minimal setup gave you minimal installation steps to get started testing the features of the GE API. This may be enough for testing purposes, but barely for production. If you are targeting a production environment, you have to carry out extra installation and configuration steps to address non-functional aspects: security (including availability), performance, etc. The Appendix also gives some recommendations on what you should do.

Administration

Tomcat

For configuring and managing Tomcat, please refer to the official user guide.

AuthzForce webapp

The AuthzForce webapp configuration directory is located here: /opt/authzforce-ce-server/conf.

In particular, the file logback.xml configures the logging for the webapp (independently from Tomcat). By default, AuthzForce-specific logs go to /var/log/tomcat10/authzforce-ce/error.log.

Restart Tomcat to apply any configuration change:

$ sudo systemctl restart tomcat10

Fast Infoset mode

Fast Infoset is an ITU-T/ISO standard for representing XML (XML Information Set to be accurate) using binary encodings, designed for use cases to provide smaller encoding sizes and faster processing than a W3C XML representation as text. The open source Fast Infoset project provide some performance results and more information about the standardisation status. There are several use cases at the origin of Fast Infoset. A major one comes from the Web3D consortium that is responsible for open standards in real-time 3D communication, and that adopted Fast Infoset for the serialization and compression of X3D documents. X3D is a standard for representing 3D scenes and objects using XML.

AuthzForce Server offers experimental support for Fast Infoset (use with caution). This feature is disabled by default. To enable Fast Infoset support, change the value of the parameter spring.profiles.active to +fastinfoset in the webapp context configuration file /etc/tomcat10/Catalina/localhost/authzforce-ce.xml; then restart Tomcat as shown in the previous section in order to apply changes.

Policy Domain Administration

The Concept of Policy Domain

The application is multi-tenant, i.e. it allows users or organizations to work on authorization policies in complete isolation from each other. In this document, we use the term domain instead of tenant. In this context, a policy domain consists of:

  • Various metadata about the domain: ID assigned by the AuthzForce API, external ID (assigned by the provisioning client), description;
  • A policy repository;
  • Attribute Providers configuration: attribute providers provide attributes that the PEP does NOT directly provide in the XACML <Request>. For example, an attribute provider may get attribute values from an external database.

The reasons for creating different domains:

  • Users or organizations do not want others to access their data, or even be impacted by others working on the same application.
  • The same user or organization may want to work on different domains for different use cases; e.g. work with one policy for production environment, another for testing, another for a specific use case project, etc.

Default Domain Settings

Administrators can set default settings for all domains to make sure domains are created in a proper configuration according to an administrative policy, or, in more simple terms, the administrator's preferences. The administrator may change these settings in the various XML files inside the folder /opt/authzforce-ce-server/conf/domain.tmpl:

  • pdp.xml:
    • maxVariableRefDepth: optional, positive integer that indicates the maximum depth of Variable reference chaining allowed in policies: VariableDefinition 1 -> VariableDefinition 2 -> ..., where -> represents a XACML VariableReference. No limit if undefined. This property applies only to policies loaded by the PDP, i.e. the root policy and policies referenced from it directly or indirectly via XACML PolicySetIdReference.
    • maxPolicyRefDepth: optional, positive integer that indicates the maximum depth of Policy(Set) reference chaining: PolicySet 1 -> PolicySet 2 -> ... -> PolicySet N; where -> represents a XACML PolicySetIdReference. No limit if undefined. This property applies only to policies loaded by the PDP, i.e. the root policy and policies referenced from it directly or indirectly via XACML PolicySetIdReference.
    • clientRequestErrorVerbosityLevel: optional, positive integer (default: 0) that sets the level of detail in the XACML StatusDetail element returned in the Indeterminate Decision Result in case of bad Request (XACML syntax/content is invalid). Increasing this value usually helps better pinpoint the reason why a particular Request was rejected by the XACML parser. This only applies to the content of the HTTP request body (XACML), it does not apply to HTTP-level errors (e.g. bad HTTP headers), in which case you get a HTTP status code 400 without any XACML response since the request is rejected before the body is passed to the XACML parser.
  • policies/cm9vdA/0.1.0.xml: the default root XACML PolicySet enforced by the PDP on the domain. As an administrator, you may change the content of this policy on two conditions:
    1. You must not change the PolicySetId.
    2. If you change the Version (e.g. to 1.2.3), you must change the filename prefix (before .xsd extension) to the same value (e.g. 1.2.3.xsd).
  • properties.xml: other domain properties, more specifically:
    • maxPolicyCount: optional, stricly positive integer that indicates the maximum number of policies on a domain, no limit if undefined.
    • maxVersionCountPerPolicy: optional, stricly positive integer that indicates the maximum number of versions per policy, no limit if undefined.
    • versionRollingEnabled: boolean, true if and only if policy versions should be rolled over, i.e. when maxVersionCountPerPolicy has been reached, oldest versions are automatically removed to make place.

Domain Creation

You create a domain by doing a HTTP POST request with XML payload to URL: http://${SERVER_NAME}:${PORT}/authzforce-ce/domains. Replace ${SERVER_NAME} and ${PORT} with your server hostname and port for HTTP. You can do it with curl tool with the the following content in a XML file (domainProperties.xml in this example) as the HTTP request body:

$ cat domainProperties.xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domainProperties
 xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5"
 externalId="external0">
 <description>This is my domain</description>
</domainProperties>

$ curl --verbose --request "POST" \
--header "Content-Type: application/xml;charset=UTF-8" \
--data @domainProperties.xml \
--header "Accept: application/xml" \
  http://${SERVER_NAME}:${PORT}/authzforce-ce/domains

...
> POST /authzforce-ce/domains HTTP/1.1
> Content-Type: application/xml;charset=UTF-8
> Accept: application/xml
> Content-Length: 227
>
...
< HTTP/1.1 200 OK
< Server: Authorization System
< Date: Mon, 04 Aug 2016 13:00:12 GMT
< Content-Type: application/xml
< Transfer-Encoding: chunked
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<link xmlns="http://www.w3.org/2005/Atom"
  rel="item" href="h_D23LsDEeWFwqVFFMDLTQ"
  title="h_D23LsDEeWFwqVFFMDLTQ"/>

WARNING: Mind the leading and trailing single quotes for the --data argument. Do not use double quotes instead of these single quotes, otherwise curl will remove the double quotes in the XML payload itself, and send invalid XML which will be rejected by the server. You may use the --trace-ascii - argument (the last dash here means stdout) instead of --verbose, in order to check the actual request body sent by curl. So use it only if you need to dump the outgoing (and incoming) data, in particular the request body, on stdout.

The href value in the response above gives you the domain ID (in the form of a Base64-encoded UUID) assigned by the API. You need this ID for any further operation on the domain.

Domain Removal

You remove a domain by doing a HTTP DELETE request with XML payload to URL: http://${SERVER_NAME}:${PORT}/authzforce-ce/domains/{domain_ID}. For example with curl tool:

$ curl --verbose --request DELETE \
 --header "Content-Type: application/xml;charset=UTF-8" \
 --header "Accept: application/xml" \
 http://${SERVER_NAME}:${PORT}/authzforce-ce/domains/h_D23LsDEeWFwqVFFMDLTQ

Policy administration is part of the Authorization Server API, addressed more extensively in the User and Programmers Guide.

High Availability

In order to achieve high availability with multiple AuthzForce Server instances (AuthzForce Server cluster), you need to make sure that the following directories are synchronized on all instances:

  • Configuration directory: /opt/authzforce-ce-server/conf. This directory is not modified by the API but only by administrators having access to the directory, and any change to it requires restarting Tomcat to apply. Therefore, this directory requires synchronization only after a manual change by a server admin, which should not occur very often. When it occurs, the server administrators may reproduce the changes on each instance manually; or, if there are too many instances for this to be practical, they may use automatic file synchronization solutions, or a distributed filesystems (e.g. NFS) combined with file monitoring solutions. Both kinds of solutions must be capable of executing a specific command, to restart Tomcat in this case, whenever a filesystem change in the directory is detected on a instance node. For example, csync2 is a solution of the first kind that is free and open source.

  • Data directory: /opt/authzforce-ce-server/data. This is where the Server API persists and retrieves domain data such as policies. Therefore, it is critical to keep this directory synchronized across all the nodes in the high availability cluster, using either file synchronization solutions such as csync2, or distributed file systems such as NFS. Besides, for usability and performance reasons, the AuthzForce server caches certain objects in memory such as domains' PDPs and ID-externalId mappings (more info in the User and Programmers Guide). Therefore, it is also critical to re-sync the AuthzForce Server cache after certain changes done directly by aforementioned solutions to the local data directory. There are two ways to do that:

    • REST API: you can keep the server in sync with the data directory by calling the following API operations, dependending on the type of change (encoded_domainId is the result of encoding the domainId using the "URL and Filename safe Base64 Alphabet" specified in Table 2 of RFC 4648):

      • HEAD /domains: to be used after any global change to the data directory. Inappropriate and largely suboptimal if there are many domains but changes concern only one or a few of them, in which case the next operations should be preferred.
      • HEAD /domains/{domainId}: to be used after a specific domain directory /opt/authzforce-ce-server/data/domains/{encoded_domainId} is created.
      • DELETE /domains/{domainId}: to be used after a specific domain directory /opt/authzforce-ce-server/data/domains/{encoded_domainId} is deleted.
      • HEAD /domains/{domainId}/properties: to be used after a specific domain's properties file /opt/authzforce-ce-server/data/domains/{encoded_domainId}/properties.xml is modified (especially the externalId property).
      • HEAD /domains/{domainId}/pap/pdp.properties: to be used after a specific domain's PDP configuration file /opt/authzforce-ce-server/data/domains/{encoded_domainId}/pdp.xml or policies directory /opt/authzforce-ce-server/data/domains/{encoded_domainId}/policies is modified.

      In these operations, you may use GET method instead of HEAD as well. However, HEAD is recommended for better performances as it does not return any content (response body), on the contrary to GET. Beware that the Content-Length returned by a HEAD is still the same as would be returned by the GET equivalent. In any case, if you opt for the file synchronization solution as mentioned earlier, you would have to make it call one of these operations depending on the type of change detected. If you opt for the distributed file system, you would need a file monitoring solution to detect changes and make such calls.

    • Embedded file monitoring threads: it is possible to enable file monitoring threads embedded in AuthzForce Server. These threads check for changes to the local data directory periodically, and synchronize the cache automatically. This feature is disabled by default. To enable it, change the value of the parameter org.ow2.authzforce.domains.sync.interval to a strictly positive integer in the webapp context configuration file /etc/tomcat10/Catalina/localhost/authzforce-ce.xml. The parameter value indicates the period between two checks for changes, in seconds. Beware that this feature creates one extra thread per domain. Therefore, the impact on memory and CPU usage increases with the number of domains. Last but not least, use this feature only on filesystems that support millisecond or higher resolution of file timestamps, such as ext4 (supports nanosecond resolution). Indeed, Authzforce file monitoring threads use file timestamps to detect changes. As a result, if the resolution of the filesystem is coarser than the millisecond, and a file change occurred in less than a second after the last check, it will go undetected (the file's mtime timestamp is not updated), and synchronization will not work as expected.

Sanity check procedures

The Sanity Check Procedures are the steps that a System Administrator will take to verify that the installation is ready to be tested. This is therefore a preliminary set of tests to ensure that obvious or basic malfunctioning is fixed before proceeding to unit tests, integration tests and user validation.

End-to-End testing

To check the proper deployment and operation of the AuthzForce Server, perform the following steps:

  1. Get the list of policy administration domains by doing the following HTTP request, replacing ${host} with the server hostname, and ${port} with the HTTP port of the server, for example with curl tool:

    $ curl --verbose --show-error --write-out '\n' \
  --request GET http://${host}:${port}/authzforce-ce/domains

  2. Check the response which should have the following headers and body (there may be more headers which do not require checking here):

    Status Code: 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resources
  xmlns="http://authzforce.github.io/rest-api-model/xmlns/authz/5"
  xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:link rel="item" href="1XepFknrEea2mQAdYFsFBQ" title="1XepFknrEea2mQAdYFsFBQ"/>
  ... list of links to other policy domains omitted here...
</resources>

You can check the exact body format in the representation element of response code 200 for method getDomains, and all other API resources and operations in general, in the WADL (Web Application Description Language) document available at the following URL:

http://${host}:${port}/authzforce-ce/?_wadl

List of Running Processes

  • One or more java processes for Tomcat.

Network interfaces Up & Open

  • TCP 22;
  • TCP 8080.

The port 8080 can be replaced by any other port Tomcat is listening to for HTTP connections to the webapp.

Databases

None.

Diagnosis Procedures

  1. Perform the test described in End-to-End testing.

  2. If you get a Connection Refused/Error, check whether Tomcat is started:

    $ sudo systemctl status tomcat10

  3. If status stopped, start Tomcat:

    $ sudo systemctl start tomcat10

  4. If Tomcat fails to start, check for any Tomcat high-level error in Tomcat log directory: /var/log/tomcat10

  5. If Tomcat is successfully started (no error in server logs), perform the test described in End-to-End testing again.

  6. If you still get a Connection Refused/error, check whether Tomcat is not listening on a different port:

    $ sudo netstat -lataupen|grep java

  7. If you still get a connection refused/error, especially if you are connecting remotely, check whether you are able to connect locally, then check the network link, i.e. whether any network filtering is in place on the host or on the access network, or other network issue: network interface status, DNS/IP adress resolution, routing, etc.

  8. If you get an error 404 Not Found, make sure the webapp is deployed and enabled in Tomcat. Check for any webapp deployment error in file: /var/log/tomcat10/authzforce-ce/error.log.

Resource availability

To have a healthy enabler, the resource requirements listed in System Requirements must be satisfied, in particular:

  • Minimum RAM: 4GB;
  • Minimum CPU: 2.6 GHz;
  • Minimum Disk space: 10 GB.

Remote Service Access

None.

Resource consumption

The resource consumption strongly depends on the number of concurrent clients and requests per client, the number of policy domains (a.k.a. tenants in this context) managed by the Authorization Server, and the complexity of the policies defined by administrators of each domain.

The memory consumption shall remain under 80% of allocated RAM. See System Requirements for the minimum required RAM.

The CPU usage shall remain under 80% of allocated CPU. See System Requirements for the minimum required CPU.

As for disk usage, at any time, there should be 1GB free space left on the disk.

I/O flows

  • HTTPS flows with possibly large XML payloads to port 8443 or whatever port Tomcat is listening to for HTTPS connections to the webapp;
  • HTTP flows with possibly large XML payloads to port 8080 or whatever port Tomcat is listening to for HTTP connections to the webapp.

Appendix

Security setup for production

You have to secure the environment of the application server and the server itself. Securing the environment of a server in general will not be addressed here, because it is a large subject for which you can find a lot of public documentation. You will learn about perimeter security, network and transport-level security (firewall, IDS/IPS...), OS security, application-level security (Web Application Firewall), etc. For instance, the NIST Guide to General Server Security (SP 800-123) is a good start.

Server Security Setup

For more Tomcat-specific security guidelines, please read Tomcat 9 Security considerations.

For security of communications (confidentiality, integrity, client/server authentication), it is also recommended to enable SSL/TLS with PKI certificates. The first step to set up this is to have your Certification Authority (PKI) issue a server certificate for your AuthzForce instance. You can also issue certificates for clients if you want to require client certificate authentication to access the AuthzForce server/API. If you don't have such a CA at hand, you can create your own (a basic one) with instructions given in the next section.

Certificate Authority Setup

If you have a CA already, you can skip this section. So this section is about creating a basic local Certificate Authority (CA) for internal use. This CA will be in charge of issuing certificates to the Authorization Server and clients, for authentication, integrity and confidentiality purposes. This procedure requires JDK 1.7 or later. (For the sake of simplicity, we do not use a subordinate CA, although you should for production, see keytool command example, use the pathlen parameter to restrict number of subordinate CA, pathlen=0 means no subordinate.)

  1. Generate the CA keypair and certificate on the platform where the Authorization Server is to be deployed (change the validity argument to your security requirements, example here is 365 days):

    $ keytool -genkeypair -keystore taz-ca-keystore.jks -alias taz-ca \
  -dname "CN=My Organization CA, O=FIWARE" -keyalg RSA -keysize 2048 \
  -validity 365 -ext bc:c="ca:true,pathlen:0"

  2. Export the CA certificate to PEM format for easier distribution to clients:

    $ keytool -keystore taz-ca-keystore.jks -alias taz-ca \
  -exportcert -rfc > taz-ca-cert.pem

Server SSL Certificate Setup

For Tomcat 9, refer to the Tomcat 9 SSL/TLS Configuration HOW-TO.

Web Application Secutity

XML and JSON Security

The AuthzForce web application exposes a XML-based API. Therefore it is vulnerable to XML denial-of-service attacks. To mitigate these attacks, there are two solutions:

  • AuthzForce native protection: you can add the following Environment entries in AuthzForce webapp context file /etc/tomcat10/Catalina/localhost/authzforce-ce.xml (if an entry is absent or its value is negative, the default value is used):

     <Environment
  name="org.apache.cxf.stax.maxChildElements"
  description="Maximum number of child elements (resp. properties) in an input XML element (resp. JSON)."
  type="java.lang.Integer"
  value="1000"
  override="false" />

 <Environment
  name="org.apache.cxf.stax.maxElementDepth"
  description="Maximum depth of an element (resp. JSON object) in input XML (resp. JSON)."
  type="java.lang.Integer"
  value="100"
  override="false" />

 <!--Following entries are not supported in Fast Infoset mode
 (more info: https://issues.apache.org/jira/browse/CXF-6848) -->
 <Environment
  name="org.apache.cxf.stax.maxAttributeCount"
  description="Maximum number of attributes per element in input XML."
  type="java.lang.Integer"
  value="100"
  override="false" />

 <Environment
  name="org.apache.cxf.stax.maxAttributeSize"
  description="Maximum size of a single attribute in input XML."
  type="java.lang.Integer"
  value="1000"
  override="false" />

 <Environment
  name="org.apache.cxf.stax.maxTextLength"
  description="Maximum size of XML text node (resp. JSON string)  in input XML (resp. JSON)."
  type="java.lang.Integer"
  value="1000"
  override="false" />

<Environment
  name="org.ow2.authzforce.domains.xacmlJsonSchemaRelativePath"
             description="Path to JSON schema file for XACML JSON Profile's Request validation, relative to ${org.ow2.authzforce.config.dir} (if undefined/empty value, the Request.schema.json file from authzforce-ce-xacml-json-model project is used by default). This property applies if and only if 'org.ow2.authzforce.domains.enableXacmlJsonProfile' is true."
 type="java.lang.String"
 value=""
 override="false" />

    Restart Tomcat to apply changes.

  • Dedicated WAF: for better mitigation, we recommend using a WAF (Web Application Firewall) with XML attack mitigation features in front of the Authzforce server.

There are commercial as well as open source WAFs available on the market. However, beware that this solution is not compatible with Fast Infoset, unless the WAF itself supports Fast Infoset. Similarly, if you want to use TLS, then the WAF or some proxy in front of it must support TLS to be the TLS server endpoint.

Disabling unused features
You can disable all PAP features, i.e. make the REST API read-only by setting the enablePdpOnly environment entry

to true in AuthzForce webapp context file /etc/tomcat10/Catalina/localhost/authzforce-ce.xml (if an entry is absent or its value is negative, the default value is used):

<Environment name="org.ow2.authzforce.domains.enablePdpOnly" value="true" type="java.lang.Boolean" override="false"
description="Enable PDP only, i.e. disable all PAP (or other administration) features iff true" />
User and Role Management Setup

In production, access to the API must be restricted and explicitly authorized. To control which clients can do what on which resources, we need to have access to user identity and attributes and assign proper roles to them. These user and role management features are no longer supported by the AuthzForce server itself, but should be delegated to the Identity Management GE.

Performance Tuning

For Tomcat and JVM tuning, we strongly recommend reading and applying - when relevant - the guidelines from the following links:

Last but not least, consider tuning the OS, hardware (CPU, RAM...), network, using load-balancing, high-availability solutions, and so on.