<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-security'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>Securing &amp; Hardening OpenIDM</title>

<indexterm>

<primary>Best practices</primary>

</indexterm>

<indexterm>

<primary>Security</primary>

</indexterm>

<para>After following the guidance in this chapter, make sure that you test

your installation to verify that it behaves as expected before putting it

into production.</para>

<para>Out of the box, OpenIDM is set up for ease of development and

deployment. When deploying OpenIDM in production, take the following

precautions.</para>

<section xml:id="security-ssl-https">

<title>Use SSL and HTTPS</title>

<indexterm>

<primary>Security</primary>

<secondary>SSL</secondary>

</indexterm>

<para>Disable plain HTTP access, included for development convenience, as

described in the section titled <link

xlink:role="http://docbook.org/xlink/role/olink"

xlink:href="integrators-guide#security-jetty"><citetitle>Secure

Jetty</citetitle></link>.</para>

<para>Use TLS/SSL to access OpenIDM, ideally with mutual authentication so

that only trusted systems can invoke each other. TLS/SSL protects data on

the wire. Mutual authentication with certificates imported into the

applications' trust and key stores provides some confidence for trusting

application access.</para>

<para>Augment this protection with message level security where

appropriate.</para>

</section>

<section xml:id="security-encrypt-data">

<title>Encrypt Data Internally &amp; Externally</title>

<indexterm>

<primary>Security</primary>

<secondary>Encryption</secondary>

</indexterm>

<indexterm>

<primary>Encryption</primary>

</indexterm>

<para>Beyond relying on end-to-end availability of TLS/SSL to protect

data, OpenIDM also supports explicit encryption of data that goes on the

wire. This can be important if the TLS/SSL termination happens prior to

the final end point.</para>

<para>OpenIDM also supports encryption of data stored in the repository,

using a symmetric key. This protects against some attacks on the data

store.</para>

<para>OpenIDM automatically encrypts sensitive data in configuration files,

such as passwords. OpenIDM replaces clear text values when the system first

reads the configuration file. Take care with configuration files having

clear text values that OpenIDM has not yet read and updated.</para>

</section>

<section xml:id="security-messages">

<title>Use Message Level Security</title>

<indexterm>

<primary>Security</primary>

<secondary>Authentication</secondary>

</indexterm>

<para>OpenIDM supports message level security, forcing authentication before

granting access. Authentication works by means of a filter-based mechanism

that lets you use either an HTTP Basic like mechanism or OpenIDM-specific

headers, setting a cookie in the response that you can use for subsequent

authentication. If you attempt to access OpenIDM URLs without the appropriate

headers or session cookie, OpenIDM returns HTTP 401 Unauthorized.</para>

<para>The following examples show successful authentications.</para>

<screen>$ curl

--dump-header /dev/stdout

--user openidm-admin:openidm-admin

"http://localhost:8080/openidm/managed/user/?_queryId=query-all-ids"

HTTP/1.1 200 OK

Set-Cookie: JSESSIONID=2l0zobpuk6st1b2m7gvhg5zas;Path=/

Expires: Thu, 01 Jan 1970 00:00:00 GMT

Content-Type: application/json; charset=UTF-8

Date: Wed, 18 Jan 2012 10:36:19 GMT

Accept-Ranges: bytes

Server: Restlet-Framework/2.0.9

Transfer-Encoding: chunked

{"query-time-ms":1,"result":[{"_id":"ajensen"},{"_id":"bjensen"}]}

$ curl

--dump-header /dev/stdout

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-admin"

"http://localhost:8080/openidm/managed/user/?_queryId=query-all-ids"

HTTP/1.1 200 OK

Set-Cookie: JSESSIONID=ixnekr105coj11ji67xcluux8;Path=/

Expires: Thu, 01 Jan 1970 00:00:00 GMT

Content-Type: application/json; charset=UTF-8

Date: Wed, 18 Jan 2012 10:36:40 GMT

Accept-Ranges: bytes

Server: Restlet-Framework/2.0.9

Transfer-Encoding: chunked

{"query-time-ms":0,"result":[{"_id":"ajensen"},{"_id":"bjensen"}]}

$ curl

--dump-header /dev/stdout

--header "Cookie: JSESSIONID=ixnekr105coj11ji67xcluux8"

"http://localhost:8080/openidm/managed/user/?_queryId=query-all-ids"

HTTP/1.1 200 OK

Content-Type: application/json; charset=UTF-8

Date: Wed, 18 Jan 2012 10:37:20 GMT

Accept-Ranges: bytes

Server: Restlet-Framework/2.0.9

Transfer-Encoding: chunked

{"query-time-ms":1,"result":[{"_id":"ajensen"},{"_id":"bjensen"}]}</screen>

<para>Notice that the last example uses the cookie OpenIDM set in the

response to the penultimate request. You can also request one-time

authentication without a session.</para>

<screen>$ curl

--dump-header /dev/stdout

--header "X-OpenIDM-NoSession: true"

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-admin"

"http://localhost:8080/openidm/managed/user/?_queryId=query-all-ids"

HTTP/1.1 200 OK

Content-Type: application/json; charset=UTF-8

Date: Wed, 18 Jan 2012 10:52:27 GMT

Accept-Ranges: bytes

Server: Restlet-Framework/2.0.9

Transfer-Encoding: chunked

{"query-time-ms":1,"result":[{"_id":"ajensen"},{"_id":"bjensen"}]}</screen>

<para>To log out and destroy the session, send the specific OpenIDM

header.</para>

<screen>$ curl

--dump-header /dev/stdout

--header "Cookie: JSESSIONID=ixnekr105coj11ji67xcluux8"

--header "X-OpenIDM-Logout: true"

"http://localhost:8080/openidm/"

HTTP/1.1 204 No Content</screen>

<para>OpenIDM creates the <literal>openidm-admin</literal> user with password

<literal>openidm-admin</literal> by default. This internal user is stored in

OpenIDM's repository.</para>

<screen>mysql&gt; select objectid,roles from internaluser;

+---------------+----------------------------------+

| objectid | roles |

+---------------+----------------------------------+

| anonymous | openidm-reg |

| openidm-admin | openidm-admin,openidm-authorized |

+---------------+----------------------------------+

2 rows in set (0.00 sec)</screen>

<indexterm>

<primary>Authentication</primary>

<secondary>Internal users</secondary>

</indexterm>

<para>OpenIDM uses the internal table for authentication, and also to set

the roles for RBAC authorization of an authenticated user. The router

service, described in the <link

xlink:role="http://docbook.org/xlink/role/olink"

xlink:href="integrators-guide#appendix-router"><citetitle>Router

Service Reference</citetitle></link> appendix, enables you to apply filters

as shown in <filename>openidm/conf/router.json</filename> and the associated

script, <filename>openidm/script/router-authz.js</filename>. See the chapter

on <link xlink:role="http://docbook.org/xlink/role/olink"

xlink:href="integrators-guide#chap-auth"><citetitle>Managing Authentication,

Authorization &amp; RBAC</citetitle></link> for details.</para>

</section>

<section xml:id="security-replace-defaults">

<title>Replace Default Security Settings</title>

<indexterm>

<primary>Passwords</primary>

</indexterm>

<para>The default security settings are adequate for evaluation purposes. For

production, change the default encryption key, and then replace the default user

password.</para>

<procedure xml:id="security-change-encryption-keys">

<title>To Change Default Encryption Keys</title>

<indexterm>

<primary>Encryption</primary>

</indexterm>

<indexterm>

<primary>Security</primary>

<secondary>Encryption</secondary>

</indexterm>

<para>By default, OpenIDM uses an symmetric encryption key with alias

<literal>openidm-sym-default</literal>. Change this default key before

deploying OpenIDM in production.</para>

<step>

<para>Add the new key to the key store.</para>

<screen>$ cd /path/to/openidm/

$ keytool

-genseckey

-alias new-sym-key

-keyalg AES

-keysize 128

-keystore security/keystore.jceks

-storetype JCEKS

Enter keystore password:

Enter key password for &lt;new-sym-key&gt;

(RETURN if same as keystore password):

Re-enter new password:

$ </screen>

<para>Also see

<filename>openidm/samples/security/keystore_readme.txt</filename>.</para>

</step>

<step>

<para>Change the alias used in

<filename>openidm/conf/boot/boot.properties</filename>.</para>

</step>

</procedure>

<procedure xml:id="security-replace-default-user-password">

<title>To Replace the Default User &amp; Password</title>

<para>After changing the default encryption key, change at least the default

user password.</para>

<step>

<para>Use the <command>encrypt</command> command to obtain the encrypted

version of the new password.</para>

<screen>$ cd /path/to/openidm/

$ cli.sh encrypt newpwd

...

-----BEGIN ENCRYPTED VALUE-----

{

"$crypto" : {

"value" : {

"iv" : "TCoC/YrmiRmINw6jCPB5LQ==",

"data" : "nCFvBIApIQ7C6k+UPzosaA==",

"cipher" : "AES/CBC/PKCS5Padding",

"key" : "openidm-sym-default"

},

"type" : "x-simple-encryption"

}

}

------END ENCRYPTED VALUE------</screen>

</step>

<step>

<para>Replace the user object in the

<filename>openidm/db/scripts/mysql/openidm.sql</filename> script before

setting up MySQL as a repository for OpenIDM.</para>

<para>Alternatively, replace the user in the internal user table.</para>

</step>

</procedure>

</section>

<section xml:id="security-jetty">

<title>Secure Jetty</title>

<indexterm>

<primary>Ports</primary>

<secondary>Disabling</secondary>

</indexterm>

<para>Before running OpenIDM in production, edit the

<filename>openidm/conf/jetty.xml</filename> configuration to avoid

clear text HTTP. Opt instead for HTTPS, either with or without mutual

authentication. To disable plain HTTP access, comment out the section in

<filename>openidm/conf/jetty.xml</filename> that enables HTTP on port

8080.</para>

<programlisting language="xml">

&lt;!--

&lt;Item&gt;

&lt;New class=&quot;org.eclipse.jetty.server.nio.SelectChannelConnector&quot;&gt;

&lt;Set name=&quot;host&quot;&gt;&lt;Property name=&quot;jetty.host&quot; /&gt;&lt;/Set&gt;

&lt;Set name=&quot;port&quot;&gt;8080&lt;/Set&gt;

&lt;Set name=&quot;maxIdleTime&quot;&gt;300000&lt;/Set&gt;

&lt;Set name=&quot;Acceptors&quot;&gt;2&lt;/Set&gt;

&lt;Set name=&quot;statsOn&quot;&gt;false&lt;/Set&gt;

&lt;Set name=&quot;confidentialPort&quot;&gt;8443&lt;/Set&gt;

&lt;Set name=&quot;lowResourcesConnections&quot;&gt;20000&lt;/Set&gt;

&lt;Set name=&quot;lowResourcesMaxIdleTime&quot;&gt;5000&lt;/Set&gt;

&lt;/New&gt;

&lt;/Item&gt;

--&gt;</programlisting>

</section>

<section xml:id="security-urls">

<title>Protect Sensitive REST Interface URLs</title>

<para>Although the repository is accessible directly by default, since

anything attached to the router is accessible with the default policy,

avoid direct HTTP access in production. If you do not need such access,

deny it in the authorization policy to reduce the attack surface.</para>

<para>Similarly deny direct HTTP access to system objects in production,

particularly access to <literal>action</literal>. As a rule of thumb, do not

expose anything that is not used in production. The main public interfaces

over HTTP are <literal>/openidm/managed/</literal> and <literal>/openidm/config/</literal>.

Other URIs are triggered indirectly, or are for internal consumption.</para>

<para>OpenIDM supports native query expressions on the JDBC repository and it

is possible to enable these over HTTP, for example:</para>

<screen width="91">$curl

--header "X-OpenIDM-Username: openidm-admin"

--header "X-OpenIDM-Password: openidm-admin"

"http://localhost:8080/openidm/managed/user?_queryExpression=select+*+from+managedobjects"</screen>

<para>By default, direct HTTP access to native queries is disallowed, and

should remain so in production systems. To enable native queries on the JDBC

repository over HTTP, specifically for testing or development purposes,

remove the custom authorization call from the router authorization script

(<filename>openidm/script/router-authz.js</filename>).</para>

<screen>"customAuthz" : "disallowQueryExpression()"</screen>

<para>Remember to remove the comma at the end of the preceding line as

well.</para>

<para>See the chapter on <link xlink:href="integrators-guide#chap-auth"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Managing

Authentication, Authorization &amp; RBAC</citetitle></link> for an example

showing how to protect sensitive URLs.</para>

</section>

<section xml:id="security-files">

<title>Protect Sensitive Files &amp; Directories</title>

<para>Protect OpenIDM files from access by unauthorized users.</para>

<para>In particular, prevent other users from reading files in at least the

<filename>openidm/conf/boot/</filename> and

<filename>openidm/security/</filename> directories.</para>

</section>

<section xml:id="security-bootstrap">

<title>Obfuscate Bootstrap Information</title>

<para>OpenIDM uses the information in

<filename>conf/boot/boot.properties</filename> including the key store

password to start up. You can set an obfuscated version in the file, or

prompt for the password at start up time.</para>

<para>To generate obfuscated versions of a password, use the

<command>encrypt</command> command-line utility. For more

information, see the <link xlink:href="integrators-guide#cli-encrypt"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>encrypt

</citetitle></link> documentation.</para>

</section>

<section xml:id="security-remove-dev-tools">

<title>Remove or Protect Development &amp; Debug Tools</title>

<para>Before deploying OpenIDM in production, remove or protect development

and debug tools, including the OSGi console exposed under

<literal>/system/console</literal>. Authentication for this console is not

integrated with authentication for OpenIDM.</para>

<para>To remove the OSGi console, remove the web console bundle,

<filename>org.apache.felix.webconsole-<replaceable>version</replaceable>.jar</filename>.</para>

<para>If you cannot remove the OSGi console, then protect it by overriding

the default <literal>admin:admin</literal> credentials. Create a file called

<filename>openidm/conf/org.apache.felix.webconsole.internal.servlet.OsgiManager.cfg</filename>

containing the user name and password to access the console in Java

properties file format.</para>

<programlisting language="ini">

username=<replaceable>user-name</replaceable>

password=<replaceable>password</replaceable></programlisting>

</section>

<section xml:id="security-protect-repo">

<title>Protect the OpenIDM Repository</title>

<para>Use the JDBC repository. OrientDB is not yet supported for production

use.</para>

<para>Use a strong password for the JDBC connection. Do not rely on default

passwords.</para>

<para>Use a case sensitive database, particularly if you work with systems

with different identifiers that match except for case. Otherwise correlation

queries can pick up identifiers that should not be considered the same.</para>

</section>

<section xml:id="security-adjust-log-levels">

<title>Adjust Log Levels</title>

<para>Leave log levels at <literal>INFO</literal> in production to ensure

that you capture enough information to help diagnose issues. See the chapter

on <link xlink:role="http://docbook.org/xlink/role/olink"

xlink:href="integrators-guide#chap-logs"><citetitle>Configuring Server

Logs</citetitle> for more information.</link>

</para>

<para>At start up and shut down, <literal>INFO</literal> can produce many

messages. Yet, during stable operation, <literal>INFO</literal> generally

results in log messages only when coarse-grain operations such as

scheduled reconciliation start or stop.</para>

</section>

<section xml:id="security-run-as-service">

<title>Set Up Restart At System Boot</title>

<para>You can run OpenIDM in the background as a service (daemon), and

add startup and shutdown scripts to manage the service at system boot

and shutdown. For details see the section titled <link

xlink:role="http://docbook.org/xlink/role/olink"

xlink:href="integrators-guide#startup-shutdown"><citetitle>Startup &amp;

Shutdown</citetitle></link>.</para>

<para>See your operating system documentation for details on adding a

service such as OpenIDM to be started at boot and shut down at system

shutdown.</para>

</section>

</chapter>