Enable Cassandra authentication

By default, Cassandra installs without authentication enabled. That means anyone can access Cassandra. You can enable authentication after installing Edge, or as part of the installation process.

You can add, remove, and modify roles by using the Cassandra CREATE/ALTER/DROP ROLES statements. For more information, see the following:

Some general considerations

  • The moment you enable Cassandra authentication, a default super user cassandra (with password cassandra) gets created automatically by Cassandra. This is a widely known super user, and you should not use this user for your production needs. Additionally, authenticating via this super user requires quorum consistency. Therefore, all connections to Cassandra authenticating via this user require stricter consistency, resulting in slower and less fault-tolerant performance.
  • A typical workflow will involve enabling authentication in Cassandra while passing a custom username and password via the configuration file. This will create the custom user and password which you can safely use for your needs, and authenticating via such users don’t have quorum consistency restrictions.
  • Remember that even though a custom user may have been created, Cassandra still creates the default cassandra super user, and your Cassandra cluster is accessible via the super user. You should typically use the ALTER ROLE command to change the password of this cassandra user to something other than the default cassandra after Cassandra authentication has been successfully enabled across the board in Apigee. Keep a record of this password for future reference.
  • You should NOT change the password of the role that edge-* components are using for authentication as that will immediately cause service disruption. Instead, you should create a brand new user, modify edge-* components to use the new user, and once complete, drop the old user using the DROP ROLE command.
  • To change the role used by edge-* components for Cassandra authentication, follow these steps:
    1. Follow the steps in the section titled Enable Authentication to create a new user. Note that if authentication is already enabled in your cluster and you have changed the password of the cassandra user, you would need to pass a username/password combination of an existing user via CASS_EXISTING_USERNAME and CASS_EXISTING_PASSWORD.
    2. Once complete, validate via cqlsh that you are able to connect to Cassandra via both the old and new user.
    3. Point all edge-* components to use the newly created user to connect to Cassandra by following the instructions in Update Edge components that connect to Cassandra.
    4. Finally, when all components are using the new user to communicate with Cassandra, you can drop the old user using the DROP ROLE command. Note that the default cassandra role should not be dropped. You can drop any custom-created roles that are not being used by edge-* components to communicate with Cassandra.
  • Remember to update the functional Cassandra username and password in the configuration file that you use for installing or upgrading Edge components. This will eliminate or minimize any disruption during edge operations.

Enable Cassandra authentication during installation

You can enable Cassandra authentication at install time.

To enable Cassandra authentication at install time, include the CASS_AUTH property in the configuration file for all Cassandra nodes:

CASS_AUTH=y # The default value is n.

The following Edge components access Cassandra:

  • Management Server
  • Message Processors
  • Routers
  • Qpid servers
  • Postgres servers

When you install these components, you must set a username and password in the configuration file:

CASS_USERNAME=cassandra_username
CASS_PASSWORD=cassandra_password

You can change the Cassandra credentials after installing Cassandra. However, if you have already installed the Management Server, Message Processors, Routers, Qpid servers, or Postgres servers, you must also update those components to use the new credentials.

To change the Cassandra credentials after installing Cassandra:

  1. Log into any one Cassandra node using the cqlsh tool and the default credentials. You only have to change the password on one node and it will be broadcast to all Cassandra nodes in the ring:
    /opt/apigee/apigee-cassandra/bin/cqlsh cassIP 9042 -u cassandra_username -p cassandra_password

    Where:

    1. cassIP is the IP address of the Cassandra node.
    2. 9042 is the default Cassandra port.
  2. Execute the following command at the cqlsh> prompt to update the password:
    ALTER ROLE <username> WITH PASSWORD='';
  3. Exit the cqlsh tool, as the following example shows:
    exit
  4. If you have not yet installed the Management Server, Message Processors, Routers, Qpid servers, or Postgres servers, set the following properties in the config file and then install those components:
    CASS_USERNAME=cassandra_username
    CASS_PASSWORD=new_cassandra_password
  5. If you have already installed the Management Server, Message Processors, Routers, Qpid servers, or Postgres servers, then see Resetting Edge Passwords for the procedure to update those components to use the new password.

Enable Cassandra authentication post installation

To enable authentication after an installation:

Update Edge components that connect to Cassandra

Use the following procedure to update all Edge components that communicate with Cassandra with the new credentials. Note that you do this step before you actually update the Cassandra credentials:

  1. On the Management Server node, run the following command:
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server
      store_cassandra_credentials -u cassandra_username -p cassandra_password

    Optionally, you can pass a file to the command containing the new username and password:

    apigee-service edge-management-server store_cassandra_credentials  -f configFile

    Where the configFile contains the following:

    CASS_USERNAME=cassandra_username # Default is cassandra
    CASS_PASSWORD='cassandra_password' # Default is cassandra; wrap in single quotes if it includes special chars

    This command automatically restarts the Management Server.

  2. For each of the following services, repeat Step 1:
    • All Message Processors
    • All Routers
    • All Qpid servers (edge-qpid-server)
    • Postgres servers (edge-postgres-server)

    When you repeat Step 1 for each service, replace edge-management-server in the command above with the appropriate service name. For example, when you execute the step for a Router service, use the following command:

    /opt/apigee/apigee-service/bin/apigee-service edge-router
      store_cassandra_credentials -u cassandra -p cassandra

Enable authentication

Use the following procedure to enable Cassandra authentication and set the username and password:

  1. Create a silent configuration file with the contents shown below:
    # Specify IP address or DNS name of cassandra node
    IP1=192.168.1.1
    IP2=192.168.1.2
    IP3=192.168.1.3
    # Must resolve to IP address or DNS name of host
    HOSTIP=$(hostname -i)
    # Set to ‘y’ to enable Cassandra authentication.
    CASS_AUTH=y # Possible values are ‘y/n’
    # Cassandra username. If it does not exist, this user would be created as a SUPERUSER
    CASS_USERNAME=cassandra_username # Default value is cassandra - don't use for production
    # Cassandra Password. If CASS_USERNAME does not exist, create SUPERUSER with this as password
    CASS_PASSWORD=cassandra_password # Default value is cassandra - don't use for production
    # Space-separated IP/DNS names of the Cassandra hosts
    CASS_HOSTS="$IP1:1,1 $IP2:1,1 $IP3:1,1"
    
    # Username of an existing C* user. Only needed if you have disabled or changed details of the default cassandra user(‘cassandra’)
    CASS_EXISTING_USERNAME=existing_cassandra_username
    # Password of an existing C* user. Only needed if you have disabled or change password of the default cassandra user(‘cassandra’)
    CASS_EXISTING_PASSWORD=existing_cassandra_password
    # Cassandra port
    CASS_PORT=9042 # The default port is 9042.
  2. Log in to the first Cassandra node and execute the following command:

    apigee-service apigee-cassandra enable_cassandra_authentication -f CONFIG

    Optionally, you can pass the properties as command arguments to the script, as shown in the following example:

    CASS_AUTH=y HOSTIP=$(hostname -i) CASS_PORT=9042 CASS_EXISTING_USERNAME=existing_cassandra_username CASS_EXISTING_PASSWORD=existing_cassandra_password CASS_USERNAME=cassandra_username CASS_PASSWORD=cassandra_password  CASS_HOSTS="192.168.1.1:1,1 192.168.1.2:1,1 192.168.1.3:1,1" apigee-service apigee-cassandra enable_cassandra_authentication

    Notes:

    • For default Cassandra credentials, the command above enables Cassandra authentication and restarts Cassandra.
    • For non-default credentials, the command also alters the replication factor, creates a superuser, and runs a repair on system_auth keyspace.
  3. Repeat steps 1 and 2 on all Cassandra nodes.