Menu Search

Chapter 8. Security

8.1. Authentication Providers

In order to successfully establish a connection to the Broker, the connection must be authenticated. The Broker supports a number of different authentication schemes, each with its own "authentication provider". Any number of Authentication Providers can be configured on the Broker at the same time.

Important

Only unused Authentication Provider can be deleted. For delete requests attempting to delete Authentication Provider associated with the Ports, the errors will be returned and delete operations will be aborted. It is possible to change the Authentication Provider on Port at runtime. However, the Broker restart is required for changes on Port to take effect.

Note

Authentication Providers may choose to selectively disable certain authentication mechanisms depending on whether an encrypted transport is being used or not. This is to avoid insecure configurations. Notably, by default the PLAIN mechanism will be disabled on non-SSL connections. This security feature can be overwritten by setting

secureOnlyMechanisms = []

in the authentication provider section of the config.json.

Warning

Changing the secureOnlyMechanism is a breach of security and might cause passwords to be transfered in the clear. Use at your own risk!

8.1.1. Simple LDAP

The Simple LDAP authenticates connections against a Directory (LDAP).

To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required:

  • LDAP server URL is the URL of the server, for example, ldaps://example.com:636

  • Search context is the distinguished name of the search base object. It defines the location from which the search for users begins, for example, dc=users,dc=example,dc=com

  • Search filter is a DN template to find an LDAP user entry by provided user name, for example, (uid={0})

Additionally, the following optional fields can be specified:

  • LDAP context factory is a fully qualified class name for the JNDI LDAP context factory. This class must implement the InitialContextFactory interface and produce instances of DirContext. If not specified a default value of com.sun.jndi.ldap.LdapCtxFactory is used.

  • LDAP authentication URL is the URL of LDAP server for performing "ldap bind". If not specified, the LDAP server URL will be used for both searches and authentications.

  • Truststore name is a name of configured truststore. Use this if connecting to a Directory over SSL (i.e. ldaps://) which is protected by a certificate signed by a private CA (or utilising a self-signed certificate).

  • Authentication method is a method of authentication to use on binding into LDAP when bind without search mode is not selected. Supported methods are NONE, SIMPLE, GSSAPI. The latter requires setting of Login Config Scope which is a name of JAAS login module from JASS login configuration file specified using JVM system property java.security.auth.login.config or Java security properties file. If Login Config Scope is not specified with GSSAPI Authentication method, the scope qpid-broker-j will be used.

  • useFullLDAPName is a boolean flag, defining whether user principal name will be obtained from full LDAP DN (default behavior) or from CN only. Set this flag to "false" to be able referencing principal by its CN in broker ACL rules.

  • Additional group information can be obtained from LDAP. There are two common ways of representing group membership in LDAP.

    • User entries can hold membership information as attribute. To use this the attribute name that holds the group information must be specified.
    • Group entries can hold a list of their members as attribute. This can be used by specifying a search context and search filter to find all groups that the user should be considered a member of. Typically this involves filtering groups by looking for the user's DN on a group attribute. The subtree search scope determines whether the search should include the subtree extending from the search context.

Important

In order to protect the security of the user's password, when using LDAP authentication, you must:

  • Use SSL on the broker's AMQP and HTTP ports to protect the password during transmission to the Broker. The Broker enforces this restriction automatically on AMQP and HTTP ports.

  • Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password during transmission from the Broker to the Directory.

The LDAP Authentication Provider works in the following manner. If not in bind without search mode, it first connects to the Directory and searches for the ldap entity which is identified by the username. The search begins at the distinguished name identified by Search Context and uses the username as a filter. The search scope is sub-tree meaning the search will include the base object and the subtree extending beneath it.

If the search returns a match, or is configured in bind without search mode, the Authentication Provider then attempts to bind to the LDAP server with the given name and the password. Note that simple security authentication is used so the Directory receives the password in the clear.

By default, this authentication provider caches the result of an authentication for a short period of time. This reduces the load on the Directory service if the same credentials are presented frequently within a short period of time. The length of time a result will be cached is defined by context variable qpid.auth.cache.expiration_time (default to 600 seconds). The cache can be disabled by setting the context variable qpid.auth.cache.size to 0.

8.1.2. Kerberos

Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the connections.

Configuration of kerberos is done through system properties (there doesn't seem to be a way around this unfortunately).

    export JAVA_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf
    ${QPID_HOME}/bin/qpid-server
  

Where qpid.conf would look something like this:

com.sun.security.jgss.accept {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    storeKey=true
    doNotPrompt=true
    realm="EXAMPLE.COM"
    useSubjectCredsOnly=false
    kdc="kerberos.example.com"
    keyTab="/path/to/keytab-file"
    principal="<name>/<host>";
};

Where realm, kdc, keyTab and principal should obviously be set correctly for the environment where you are running (see the existing documentation for the C++ broker about creating a keytab file).

8.1.2.1. SPNEGO Authentication

SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) based authentication can be configured for Web Management Console and REST API.

A special JAAS login configuration needs to be provided for Service Principal Name (SPN) HTTP/{FQDN}@REALM in addition to configuration provided for broker service principal in scope com.sun.security.jgss.accept. An example of such SPNEGO configuration is provided below,

spnego {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    storeKey=true
    doNotPrompt=true
    realm="EXAMPLE.COM"
    useSubjectCredsOnly=false
    kdc="kerberos.example.com"
    keyTab="/path/to/keytab-file-for-HTTP-principal"
    principal="HTTP/broker.org";
};

Important

Please, note that in the example above a principal name is specified as HTTP/broker.org where broker.org is supposed to be a fully qualified name of the host where broker is running. The FQDN used to access the Broker must match the host name in the SPN exactly otherwise the authentication will fail.

A name of configuration module in the example above is spnego. It can be communicated to the Kerberos authentication provider via context variable or JVM system property qpid.auth.gssapi.spnegoConfigScope. For example,

        export QPID_OPTS=-Dqpid.auth.gssapi.spnegoConfigScope=spnego -Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf
    

The RELM part in name of authenticated principal logged with SPNEGO mechanism can be stripped by setting context variable qpid.auth.gssapi.spnegoStripRealmFromPrincipalName to true.

8.1.3. OAuth2

This authentication provider allows users to login to the broker using credentials from a different service supporting OAuth2. Unfortunately, the OAuth2 specification does not define a standard why to get the identity of a subject from an access token. However, most OAuth2 implementations provide such functionality, although in different ways. Qpid handles this by providing so called IdentityResolvers. Currently the following services are supported:

  • CloudFoundry

  • Facebook

  • GitHub

  • Google

  • Microsoft Live

Since all of these, with the exception of CloudFoundry, are tied to a specific service they come with defaults for the Scope, Authorization-, Token-, and IdentityResolverEndpoint.

By default, this authentication provider caches the result of an authentication for a short period of time. This reduces the load on the OAuth2 service if the same token is presented frequently within a short period of time. The length of time a result will be cached is defined by context variable qpid.auth.cache.expiration_time (default to 600 seconds). The cache can be disabled by setting the context variable qpid.auth.cache.size to 0.

8.1.4. External (SSL Client Certificates)

When requiring SSL Client Certificates be presented the External Authentication Provider can be used, such that the user is authenticated based on trust of their certificate alone, and the X500Principal from the SSL session is then used as the username for the connection, instead of also requiring the user to present a valid username and password.

Note: The External Authentication Provider should typically only be used on the AMQP/HTTP ports, in conjunction with SSL client certificate authentication. It is not intended for other uses and will treat any non-sasl authentication processes on these ports as successful with the given username.

On creation of External Provider the use of full DN or username CN as a principal name can be configured. If attribute "Use the full DN as the Username" is set to "true" the full DN is used as an authenticated principal name. If attribute "Use the full DN as the Username" is set to "false" the user name CN part is used as the authenticated principal name. Setting the field to "false" is particular useful when ACL is required, as at the moment, ACL does not support commas in the user name.

8.1.5. Anonymous

The Anonymous Authentication Provider will allow users to connect with or without credentials and result in their identification on the broker as the user ANONYMOUS. This Provider does not require specification of any additional attributes on creation.

8.1.6. SCRAM SHA

The SCRAM SHA Providers uses the Broker configuration itself to store the database of users. The users' passwords are stored as salted SHA digested password. This can be further encrypted using the facilities described in Section 8.5, “Configuration Encryption”.

There are two variants of this provider, SHA1 and SHA256. SHA256 is recommended whenever possible. SHA1 is provided with compatibility with clients utilising JDK 1.6 (which does not support SHA256).

For these providers user credentials can be added, removed or changed using Management.

8.1.7. Plain

The Plain Provider uses the Broker configuration itself to store the database of users (unlike the PlainPasswordFile, there is no separate password file). As the name suggests, the user data (including password) is not hashed in any way. In order to provide encryption, the facilities described in Section 8.5, “Configuration Encryption” must be used.

For this provider user credentials can be added, removed or changed using Management.

8.1.8. Plain Password File (Deprecated)

This provider is deprecated and will be removed in a future release. The Plain provider should be used instead.

The PlainPasswordFile Provider uses local file to store and manage user credentials. When creating an authentication provider the path to the file needs to be specified. If specified file does not exist an empty file is created automatically on Authentication Provider creation. On Provider deletion the password file is deleted as well.

For this provider user credentials can be added, removed or changed using Management.

8.1.8.1. Plain Password File Format

The user credentials are stored on the single file line as user name and user password pairs separated by colon character. This file must not be modified externally whilst the Broker is running.

# password file format
# <user name>: <user password>
guest:guest
        

8.1.9. MD5 Provider

MD5 Provider uses the Broker configuration itself to store the database of users (unlike the Base64MD5 Password File, there is no separate password file). Rather than store the unencrypted user password (as the Plain provider does) it instead stores the MD5 password digest. This can be further encrypted using the facilities described in Section 8.5, “Configuration Encryption”.

For this provider user credentials can be added, removed or changed using Management.

8.1.10. Base64MD5 Password File (Deprecated)

This provider is deprecated and will be removed in a future release. The MD5 provider should be used instead.

Base64MD5PasswordFile Provider uses local file to store and manage user credentials similar to PlainPasswordFile but instead of storing a password the MD5 password digest encoded with Base64 encoding is stored in the file. When creating an authentication provider the path to the file needs to be specified. If specified file does not exist an empty file is created automatically on Authentication Provider creation. On Base64MD5PasswordFile Provider deletion the password file is deleted as well.

For this provider user credentials can be added, removed or changed using Management.

8.1.10.1. Base64MD5 File Format

The user credentials are stored on the single file line as user name and user password pairs separated by colon character. The password is stored MD5 digest/Base64 encoded. This file must not be modified externally whilst the Broker is running.

8.1.11. Composite Provider

Composite Provider uses existing username / password authentication providers allowing to perform authentication against them in order defined. It can contains following authentication providers:

When performing authentication, composite provider checks presence of a user with a given username in the first delegate provider and if found, performs authentication. It should be considered, that in case of name collision (when delegate providers contains users with same username but different passwords), it's not guaranteed that authentication will succeed even with the correct credentials. Therefore username collision should be avoided, i.e. each delegate provider should contain users with unique usernames.

Table 8.1. SASL Mechanisms

Authentication providerSASL mechanisms
MD5 ProviderPLAIN, CRAM-MD5-HASHED, CRAM-MD5-HEX
PlainPLAIN, CRAM-MD5, SCRAM-SHA-1, SCRAM-SHA-256
SCRAM SHA ProvidersPLAIN, SCRAM-SHA-1, SCRAM-SHA-256
Simple LDAP ProvidersPLAIN

Composite provider exposes intersection of SASL mechanism provided by its delegates.