-
Notifications
You must be signed in to change notification settings - Fork 66
Security
Roxy lets you configure your application's security, so that roles, users, privileges and amps get set up when you bootstrap. Here's how to work with each of them.
Roles are the foundation of security within MarkLogic. The default.properties file specifies an application-specific role that will be given the permissions and privileges needed to run your application and to read and update your data, as well as read and execute your modules.
# The role that is given permissions and execute privileges
app-role=${app-name}-role
To give it a different name, you can override this setting in build.properties.
The app-role's initial configuration is provided in ml-config.xml. Here are examples of adding more details to the default role configuration:
<roles xmlns="http://marklogic.com/xdmp/security">
<role>
<role-name>@ml.app-role</role-name>
<description>A role for users of the @ml.app-name application</description>
<role-names>
<role-name>some-role</role-name>
</role-names>
<permissions>
<permission>
<role-name>some-role</role-name>
<capability>read</capability>
</permission>
</permissions>
<collections>
<collection>junk</collection>
</collections>
<privileges>
<privilege>
<privilege-name>xdmp:add-response-header</privilege-name>
</privilege>
<privilege>
<privilege-name>unprotected-uri</privilege-name>
</privilege>
<privilege>
<privilege-name>user-get-roles</privilege-name>
</privilege>
<privilege>
<privilege-name>xdmp:eval</privilege-name>
</privilege>
<privilege>
<privilege-name>xdmp:eval-in</privilege-name>
</privilege>
<privilege>
<privilege-name>xdmp:invoke</privilege-name>
</privilege>
<privilege>
<privilege-name>xdmp:invoke-in</privilege-name>
</privilege>
<privilege>
<privilege-name>xdmp:value</privilege-name>
</privilege>
</privileges>
</role>
</roles>You can additional role elements to define more roles.
In an application with application-layer security, you will need to select a default user. Choosing admin effectively turns off security. You can use the built-in "nobody" user, but you might need a different set of privileges. Rather than potentially affecting other applications on the server, it's better to set up your own roles and create your own user. The default user is set in build.properties:
#
# The user used as the default user in application level authentication.
# Using the admin user as the default user is equivalent to turning security off.
#
# default-user=${app-name}-user
The property is initially commented out, but to change it, you can un-comment it and set it to whatever name you like. Your ml-config.xml file has examples of adding roles. To set permissions and collections at the user level, follow the same format used to set them for roles.
You may have noticed that privileges are referred to by name only in the role definition section above. Your application may need both built-in privileges and custom privileges for your application. Custom privileges are defined under /configuration/sec:privileges -- these privileges will be created with bootstrap and destroyed with wipe.
HTTP servers can be configured to use an SSL certificate template, which applies server-side SSL security. These features are available in Roxy 1.4.
To create a certificate template, you'll need at least two properties plus an element defined in ml-config.xml.
These properties are used in creating a certificate template:
- ssl-certificate-template=roxy
- ssl-certificate-countryName=
- ssl-certificate-stateOrProvinceName=
- ssl-certificate-localityName=
- ssl-certificate-organizationName=My Org
- ssl-certificate-organizationalUnitName=
- ssl-certificate-emailAddress=
ssl-certificate-template and ssl-certificate-organizationName are required.
In deploy/ml-config.xml, have this element defined as a child of the root configuration element:
<certificates xmlns="http://marklogic.com/xdmp/pki">
<certificate>
<name>@ml.ssl-certificate-template</name>
<countryName>@ml.ssl-certificate-countryName</countryName>
<stateOrProvinceName>@ml.ssl-certificate-stateOrProvinceName</stateOrProvinceName>
<localityName>@ml.ssl-certificate-localityName</localityName>
<organizationName>@ml.ssl-certificate-organizationName</organizationName>
<organizationalUnitName>@ml.ssl-certificate-organizationalUnitName</organizationalUnitName>
<emailAddress>@ml.ssl-certificate-emailAddress</emailAddress>
</certificate>
</certificates>
The effect of defining these properties and the certificates element is that during bootstrapping, a certificate template will be created and the HTTP app server will use it. If the project is set up to create a unit testing HTTP app server, that app server will also use SSL.
To skip the creation of a template but use an existing one to secure the HTTP app servers, specify the ssl-certificate-template property with the name of the template. If the certificates element exists in ml-config.xml and the named template does not exist on the target server, the certificate will be created. You can prevent this with either of two approaches:
- Comment out or delete the certificates element from ml-config.xml
- Specify the ssl-certificate-template property only in the {env}.properties files for the environments where the template already exists. For instance, you might define it in prop.properties but not local.properties, in order to secure the production server while not using SSL on your local server.
You can verify that you have set it up correctly using the info command.
$ ml prod info | grep ssl-certificate-template
ml.ssl-certificate-template:roxy
$ ml local info | grep ssl-certificate-template
ml.ssl-certificate-template: