Aurora integrates with Apache Shiro to provide security controls for its API. In addition to providing some useful features out of the box, Shiro also allows Aurora cluster administrators to adapt the security system to their organization’s existing infrastructure. The announcer in the Aurora thermos executor also supports security controls for talking to ZooKeeper.
There are two major components of security: authentication and authorization. A cluster administrator may choose the approach used for each, and may also implement custom mechanisms for either. Later sections describe the options available. To enable authentication for the announcer, see Announcer Authentication
The scheduler must be configured with instructions for how to process authentication credentials at a minimum. There are currently two built-in authentication schemes - HTTP Basic Authentication, and SPNEGO (Kerberos).
Basic Authentication is a very quick way to add some security. It is supported by all major browsers and HTTP client libraries with minimal work. However, before relying on Basic Authentication you should be aware of the security considerations.
At a minimum you need to set 4 command-line flags on the scheduler:
-http_authentication_mechanism=BASIC
-shiro_realm_modules=INI_AUTHNZ
-shiro_ini_path=path/to/security.ini
And create a security.ini file like so:
[users]
sally = apple, admin
[roles]
admin = *
The details of the security.ini file are explained below. Note that this file contains plaintext, unhashed passwords.
To configure the client for HTTP Basic authentication, add an entry to ~/.netrc with your credentials
% cat ~/.netrc
# ...
machine aurora.example.com
login sally
password apple
# ...
No changes are required to clusters.json.
At a minimum you need to set 6 command-line flags on the scheduler:
-http_authentication_mechanism=NEGOTIATE
-shiro_realm_modules=KERBEROS5_AUTHN,INI_AUTHNZ
-kerberos_server_principal=HTTP/aurora.example.com@EXAMPLE.COM
-kerberos_server_keytab=path/to/aurora.example.com.keytab
-shiro_ini_path=path/to/security.ini
And create a security.ini file like so:
% cat path/to/security.ini
[users]
sally = _, admin
[roles]
admin = *
What’s going on here? First, Aurora must be configured to request Kerberos credentials when presented with an unauthenticated request. This is achieved by setting
-http_authentication_mechanism=NEGOTIATE
Next, a Realm module must be configured to authenticate the current request using the Kerberos credentials that were requested. Aurora ships with a realm module that can do this
-shiro_realm_modules=KERBEROS5_AUTHN[,...]
The Kerberos5Realm requires a keytab file and a server principal name. The principal name will usually
be in the form HTTP/aurora.example.com@EXAMPLE.COM.
-kerberos_server_principal=HTTP/aurora.example.com@EXAMPLE.COM
-kerberos_server_keytab=path/to/aurora.example.com.keytab
The Kerberos5 realm module is authentication-only. For scheduler security to work you must also enable a realm module that provides an Authorizer implementation. For example, to do this using the IniShiroRealmModule:
-shiro_realm_modules=KERBEROS5_AUTHN,INI_AUTHNZ
You can then configure authorization using a security.ini file as described below (the password field is ignored). You must configure the realm module with the path to this file:
-shiro_ini_path=path/to/security.ini
To use Kerberos on the client-side you must build Kerberos-enabled client binaries. Do this with
./pants binary src/main/python/apache/aurora/kerberos:kaurora
./pants binary src/main/python/apache/aurora/kerberos:kaurora_admin
You must also configure each cluster where you’ve enabled Kerberos on the scheduler
to use Kerberos authentication. Do this by setting auth_mechanism to KERBEROS
in clusters.json.
% cat ~/.aurora/clusters.json
{
"devcluser": {
"auth_mechanism": "KERBEROS",
...
},
...
}
Given a means to authenticate the entity a client claims they are, we need to define what privileges they have.
The simplest security configuration for Aurora is an INI file on the scheduler. For small clusters, or clusters where the users and access controls change relatively infrequently, this is likely the preferred approach. However you may want to avoid this approach if access permissions are rapidly changing, or if your access control information already exists in another system.
You can enable INI-based configuration with following scheduler command line arguments:
-http_authentication_mechanism=BASIC
-shiro_ini_path=path/to/security.ini
note As the argument name reveals, this is using Shiro’s IniRealm behind the scenes.
The INI file will contain two sections - users and roles. Here’s an example for what might be in security.ini:
[users]
sally = apple, admin
jim = 123456, accounting
becky = letmein, webapp
larry = 654321,accounting
steve = password
[roles]
admin = *
accounting = thrift.AuroraAdmin:setQuota
webapp = thrift.AuroraSchedulerManager:*:webapp
The users section defines user user credentials and the role(s) they are members of. These lines
are of the format <user> = <password>[, <role>...]. As you probably noticed, the passwords are
in plaintext and as a result read access to this file should be restricted.
In this configuration, each user has different privileges for actions in the cluster because of the roles they are a part of:
You might find documentation on the Internet suggesting there are additional sections in shiro.ini,
like [main] and [urls]. These are not supported by Aurora as it uses a different mechanism to configure
those parts of Shiro. Think of Aurora’s security.ini as a subset with only [users] and [roles] sections.
It is possible to leverage Shiro’s runAs feature by implementing a custom Servlet Filter that provides
the capability and passing it’s fully qualified class name to the command line argument
-shiro_after_auth_filter. The filter is registered in the same filter chain as the Shiro auth filters
and is placed after the Shiro auth filters in the filter chain. This ensures that the Filter is invoked
after the Shiro filters have had a chance to authenticate the request.
Since Aurora’s security is backed by Apache Shiro, you can implement a custom Realm to define organization-specific security behavior.
In addition to using Shiro’s standard APIs to implement a Realm you can link against Aurora to
access the type-safe Permissions Aurora uses. See the Javadoc for org.apache.aurora.scheduler.spi
for more information.
Package your custom Realm(s) with a Guice module that exposes a Set<Realm> multibinding.
package com.example;
import com.google.inject.AbstractModule;
import com.google.inject.multibindings.Multibinder;
import org.apache.shiro.realm.Realm;
public class MyRealmModule extends AbstractModule {
@Override
public void configure() {
Realm myRealm = new MyRealm();
Multibinder.newSetBinder(binder(), Realm.class).addBinding().toInstance(myRealm);
}
static class MyRealm implements Realm {
// Realm implementation.
}
}
To use your module in the scheduler, include it as a realm module based on its fully-qualified class name:
-shiro_realm_modules=KERBEROS5_AUTHN,INI_AUTHNZ,com.example.MyRealmModule
The Thermos executor can be configured to authenticate with ZooKeeper and include
an ACL
on the nodes it creates, which will specify
the privileges of clients to perform different actions on these nodes. This
feature is enabled by specifying an ACL configuration file to the executor with the
--announcer-zookeeper-auth-config command line argument.
When this feature is not enabled, nodes created by the executor will have ‘world/all’ permission
(ZOO_OPEN_ACL_UNSAFE). In most production environments, operators should specify an ACL and
limit access.
The configuration file must be formatted as JSON with the following schema:
{
"auth": [
{
"scheme": "<scheme>",
"credential": "<plain_credential>"
}
],
"acl": [
{
"scheme": "<scheme>",
"credential": "<plain_credential>",
"permissions": {
"read": <bool>,
"write": <bool>,
"create": <bool>,
"delete": <bool>,
"admin": <bool>
}
}
]
}
The scheme
defines the encoding of the credential field. Note that these fields are passed directly to
ZooKeeper (except in the case of digest scheme, where the executor will hash and encode
the credential appropriately before passing it to ZooKeeper). In addition to acl, a list of
authentication credentials must be provided in auth to use for the connection.
All properties of the permissions object will default to False if not provided.
To enable the executor to authenticate against ZK, --announcer-zookeeper-auth-config should be
set to the configuration file.
The Aurora scheduler does not provide native HTTPS support (AURORA-343). It is therefore recommended to deploy it behind an HTTPS capable reverse proxy such as nginx or Apache2.
A simple setup is to launch both the reverse proxy and the Aurora scheduler on the same port, but bind the reverse proxy to the public IP of the host and the scheduler to localhost:
-ip=127.0.0.1
-http_port=8081
If your clients connect to the scheduler via proxy_url,
you can update it to https. If you use the ZooKeeper based discovery instead, the scheduler
needs to be launched via
-serverset_endpoint_name=https
in order to announce its HTTPS support within ZooKeeper.
While the APIs and SPIs we ship with are stable as of 0.8.0, we are aware of several incremental improvements. Please follow, vote, or send patches.
Relevant tickets: * AURORA-1248: Client retries 4xx errors * AURORA-1279: Remove kerberos-specific build targets * AURORA-1293: Consider defining a JSON format in place of INI * AURORA-1179: Supported hashed passwords in security.ini * AURORA-1295: Support security for the ReadOnlyScheduler service