Join us on
Star us on
Get Started
Slack
GitHub
Get Started
v2.5 (latest) v2.2 (stable) v2.1 (earlier version) v2.0 (earlier version) v1.3 (earlier version)
  • GET STARTED
    • Quick start
      • 1. Install YugabyteDB
      • 2. Create a local cluster
      • 3. Explore YSQL
      • 4. Build an application
        • Java
        • NodeJS
        • Go
        • Python
        • Ruby
        • C#
        • PHP
        • C++
        • C
    • Introduction
    • Explore core
      • 1. Linear scalability
      • 2. Fault tolerance
      • 3. Global distribution
      • 4. Auto sharding
      • 5. Tunable reads
      • 6. Observability
  • USER GUIDES
    • Develop
      • Learn app development
        • 1. SQL vs NoSQL
        • 2. Data modeling
        • 3. Data types
        • 4. ACID transactions
        • 5. Aggregations
        • 6. Batch operations
        • 7. Date and time
        • 8. Strings and text
      • Ecosystem integrations
        • Apache Kafka
        • Apache Spark
        • JanusGraph
        • KairosDB
        • Presto
        • Metabase
      • Real-world examples
        • E-Commerce App
        • IoT Fleet Management
        • Retail Analytics
      • Explore sample applications
    • Deploy
      • Checklist
      • Manual deployment
        • 1. System configuration
        • 2. Install software
        • 3. Start YB-Masters
        • 4. Start YB-TServers
        • 5. Verify deployment
      • Kubernetes
        • Helm Chart
        • Helm configuration
        • Local SSD
      • Docker
      • Public clouds
        • Amazon Web Services
        • Google Cloud Platform
        • Microsoft Azure
      • Pivotal Cloud Foundry
      • Yugabyte Platform
        • 1. Prepare cloud environment
        • 2. Install Admin Console
        • 3. Configure Admin Console
        • 4. Configure Cloud Providers
    • Benchmark
      • Performance
      • YCSB
      • Large datasets
    • Secure
      • Security checklist
      • Authentication
      • Authorization
        • 1. RBAC Model
        • 2. Create Roles
        • 3. Grant permissions
      • TLS encryption
        • 1. Prepare nodes
        • 2. Server-server encryption
        • 3. Client-server encryption
        • 4. Connect to cluster
      • Encryption at Rest
    • Manage
      • Backup and restore
        • Backing up data
        • Restoring data
      • Data migration
        • Bulk import
        • Bulk export
      • Change cluster config
      • Upgrade deployment
      • Diagnostics reporting
      • Yugabyte Platform
        • Create universe - Multi-zone
        • Create universe - Multi-region
        • Edit universe
        • Edit config flags
        • Health checking and alerts
        • Create and edit instance tags
        • Node status and actions
        • Read replicas
        • Back up and restore
        • Upgrade universe
        • Delete universe
    • Troubleshoot
      • Troubleshooting overview
      • Cluster level issues
        • YCQL connection issues
        • YEDIS connection Issues
      • Node level issues
        • Check processes
        • Inspect logs
        • System statistics
      • Yugabyte Platform
        • Troubleshoot universes
  • REFERENCE
    • APIs
      • YSQL
        • Statements
          • ABORT
          • ALTER DATABASE
          • ALTER DOMAIN
          • ALTER TABLE
          • BEGIN
          • COMMENT
          • COMMIT
          • COPY
          • CREATE DATABASE
          • CREATE DOMAIN
          • CREATE INDEX
          • CREATE SCHEMA
          • CREATE SEQUENCE
          • CREATE TABLE
          • CREATE TABLE AS
          • CREATE TYPE
          • CREATE USER
          • CREATE VIEW
          • DEALLOCATE
          • DELETE
          • DROP DATABASE
          • DROP DOMAIN
          • DROP SEQUENCE
          • DROP TABLE
          • DROP TYPE
          • END
          • EXECUTE
          • EXPLAIN
          • GRANT
          • INSERT
          • LOCK
          • PREPARE
          • RESET
          • REVOKE
          • ROLLBACK
          • SELECT
          • SET
          • SET CONSTRAINTS
          • SET TRANSACTION
          • SHOW
          • SHOW TRANSACTION
          • TRUNCATE
          • UPDATE
        • Data types
          • Binary
          • Boolean
          • Character
          • Date-time
          • Json
          • Money
          • Numeric
          • Serial
          • UUID
        • Expressions
          • currval()
          • lastval()
          • nextval()
        • Keywords
        • Reserved Names
      • YCQL
        • Quick Start YCQL
        • ALTER KEYSPACE
        • ALTER ROLE
        • ALTER TABLE
        • CREATE INDEX
        • CREATE KEYSPACE
        • CREATE ROLE
        • CREATE TABLE
        • CREATE TYPE
        • DROP INDEX
        • DROP KEYSPACE
        • DROP ROLE
        • DROP TABLE
        • DROP TYPE
        • GRANT PERMISSION
        • GRANT ROLE
        • REVOKE PERMISSION
        • REVOKE ROLE
        • USE
        • INSERT
        • SELECT
        • UPDATE
        • DELETE
        • TRANSACTION
        • TRUNCATE
        • Simple Value
        • Subscript
        • Function Call
        • Operator Call
        • BLOB
        • BOOLEAN
        • MAP, SET, LIST
        • FROZEN
        • INET
        • Integer & Counter
        • Non-Integer
        • TEXT
        • Date & Time Types
        • UUID & TIMEUUID
        • JSONB
        • Date and time functions
    • CLIs
      • yb-ctl
      • yb-docker-ctl
      • yb-master
      • yb-tserver
      • ysqlsh
      • cqlsh
    • Sample data
      • Chinook
      • Northwind
      • PgExercises
      • SportsDB
    • Tools
      • TablePlus
  • RELEASES
    • Release history
      • v1.3.1
      • v1.3.0
      • v1.2.12
      • v1.2.11
      • v1.2.10
      • v1.2.9
      • v1.2.8
      • v1.2.6
      • v1.2.5
      • v1.2.4
  • CONCEPTS
    • Architecture
      • Design goals
      • Layered architecture
      • Basic concepts
        • Universe
        • YB-TServer
        • YB-Master
        • Acknowledgements
      • Query layer
        • Overview
      • DocDB store
        • Sharding
        • Replication
        • Persistence
        • Performance
      • DocDB transactions
        • Isolation Levels
        • Single row transactions
        • Distributed transactions
        • Transactional IO path
  • FAQ
    • Comparisons
      • CockroachDB
      • Google Cloud Spanner
      • MongoDB
      • FoundationDB
      • Amazon DynamoDB
      • Azure Cosmos DB
      • Apache Cassandra
      • Redis in-memory store
      • Apache HBase
    • Other FAQs
      • Product
      • Architecture
      • Yugabyte Platform
      • API compatibility
  • CONTRIBUTOR GUIDES
    • Get involved
  • Misc
    • YEDIS
      • Quick start
      • Develop
        • Client drivers
          • C
          • C++
          • C#
          • Go
          • Java
          • NodeJS
          • Python
      • API reference
        • APPEND
        • AUTH
        • CONFIG
        • CREATEDB
        • DELETEDB
        • LISTDB
        • SELECT
        • DEL
        • ECHO
        • EXISTS
        • EXPIRE
        • EXPIREAT
        • FLUSHALL
        • FLUSHDB
        • GET
        • GETRANGE
        • GETSET
        • HDEL
        • HEXISTS
        • HGET
        • HGETALL
        • HINCRBY
        • HKEYS
        • HLEN
        • HMGET
        • HMSET
        • HSET
        • HSTRLEN
        • HVALS
        • INCR
        • INCRBY
        • KEYS
        • MONITOR
        • PEXPIRE
        • PEXPIREAT
        • PTTL
        • ROLE
        • SADD
        • SCARD
        • RENAME
        • SET
        • SETEX
        • PSETEX
        • SETRANGE
        • SISMEMBER
        • SMEMBERS
        • SREM
        • STRLEN
        • ZRANGE
        • TSADD
        • TSCARD
        • TSGET
        • TSLASTN
        • TSRANGEBYTIME
        • TSREM
        • TSREVRANGEBYTIME
        • TTL
        • ZADD
        • ZCARD
        • ZRANGEBYSCORE
        • ZREM
        • ZREVRANGE
        • ZSCORE
        • PUBSUB
        • PUBLISH
        • SUBSCRIBE
        • UNSUBSCRIBE
        • PSUBSCRIBE
        • PUNSUBSCRIBE
Authentication
> Secure >

Authentication

Instructions for enabling authentication in YugabyteDB.

Attention

This page documents an earlier version. Go to the latest (v2.3) version.

Authentication should be enabled to verify the identity of a client that connects to YugabyteDB. Note the following:

  • Authentication is implemented for YCQL (Cassandra-compatible) and YEDIS (Redis-compatible) APIs currently.

  • For YCQL, enabling authentication automatically enables authorization or role based access control (RBAC) to determine the access privileges. Authentication verifies the identity of a user while authorization determines the verified user’s access privileges to the database.

  • YCQL
  • YEDIS

Overview

YCQL authentication is based on roles. Roles can be created with superuser, non-superuser and login privileges. New roles can be created, and existing ones altered or dropped by administrators using CQL commands.

1. Enable YCQL authentication

You can enable access control by starting the yb-tserver processes with the --use_cassandra_authentication=true flag. Your command should look similar to that shown below:

./bin/yb-tserver \
  --tserver_master_addrs <master addresses> \
  --fs_data_dirs <data directories> \
  --use_cassandra_authentication=true \
  >& /home/centos/disk1/yb-tserver.out &

You can read more about bringing up the YB-TServers for a deployment in the section on manual deployment of a YugabyteDB cluster.

2. Connect with the default admin credentials

A new YugabyteDB cluster with authentication enabled comes up with a default admin user, the default username/password for this admin user is cassandra/cassandra. Note that this default user has SUPERUSER privilege. You can connect to this cluster using cqlsh as follows:

$ cqlsh -u cassandra -p cassandra

You should see the cluster connect and the following prompt:

Connected to local cluster at 127.0.0.1:9042.
[cqlsh 5.0.1 | Cassandra 3.9-SNAPSHOT | CQL spec 3.4.2 | Native protocol v4]
Use HELP for help.
[email protected]>

3. Create a new user

Use the CREATE ROLE statement to create a new role. Users are roles that have the LOGIN privilege granted to them. Roles created with the SUPERUSER option in addition to the LOGIN option have full access to the database. Superusers can run all the CQL commands on any of the database resources.

NOTE By default, creating a role does not grant the LOGIN or the SUPERUSER privileges, these need to be explicitly granted.

Creating a user

For example, to create a regular user john with the password PasswdForJohn and grant login privileges, run the following command.

cassandra@cqlsh> CREATE ROLE IF NOT EXISTS john WITH PASSWORD = 'PasswdForJohn' AND LOGIN = true;

If the role john already existed, the above statement will not error out since we have added the IF NOT EXISTS clause. To verify the user account just created, run the following query:

cassandra@cqlsh> SELECT role, can_login, is_superuser, member_of FROM system_auth.roles;

You should see the following output.

 role      | can_login | is_superuser | member_of
-----------+-----------+--------------+-----------
      john |      True |        False |          []
 cassandra |      True |         True |          []

(2 rows)

Creating a superuser

The SUPERUSER status should be given only to a limited number of users. Applications should generally not access the database using an account that has the superuser privilege.

NOTE Only a role with the SUPERUSER privilege can create a new role with the SUPERUSER privilege, or grant it to an existing role.

To create a superuser admin with the LOGIN privilege, run the following command using a superuser account:

cassandra@cqlsh> CREATE ROLE admin WITH PASSWORD = 'PasswdForAdmin' AND LOGIN = true AND SUPERUSER = true;

To verify the admin account just created, run the following query.

cassandra@cqlsh> SELECT role, can_login, is_superuser, member_of FROM system_auth.roles;

You should see the following output.

 role      | can_login | is_superuser | member_of
-----------+-----------+--------------+-----------
     admin |      True |         True |          []
      john |      True |        False |          []
 cassandra |      True |         True |          []

(3 rows)

4. Connect to cqlsh using non-default credentials

You can connect to a YCQL cluster with authentication enabled as follows:

$ cqlsh -u <username> -p <password>

Alternatively, you can omit the -p <password> above and you will be prompted for a password.

As an example of connecting as a user, we can login with the credentials of the user john that we created above by running the following command and entering the password when prompted:

$ cqlsh -u john

As an example of connecting as the admin user, we can run the following command.

$ cqlsh -u admin -p PasswdForAdmin

5. Edit user accounts

You can edit existing user accounts using the ALTER ROLE command. Note that the role making these changes should have sufficient privileges to modify the target role.

Changing password for a user

To change the password for john above, you can do:

cassandra@cqlsh> ALTER ROLE john WITH PASSWORD = 'new-password';

Granting and removing superuser privileges

In the example above, we can verify that john is not a superuser:

cassandra@cqlsh> SELECT role, can_login, is_superuser, member_of FROM system_auth.roles WHERE role='john';
 role | can_login | is_superuser | member_of
------+-----------+--------------+-----------
 john |      True |        False |          []

(1 rows)

To grant superuser privileges to john, run the following command.

cassandra@cqlsh> ALTER ROLE john WITH SUPERUSER = true;

We can now verify that john is now a superuser.

cassandra@cqlsh> SELECT role, can_login, is_superuser, member_of FROM system_auth.roles WHERE role='john';
 role | can_login | is_superuser | member_of
------+-----------+--------------+-----------
 john |      True |         True |          []

(1 rows)

Similarly, you can revoke superuser privileges by running:

cassandra@cqlsh> ALTER ROLE john WITH SUPERUSER = false;

Enable and disable login privileges

In the example above, we can verify that john is can login to the database by doing the following:

cassandra@cqlsh> SELECT role, can_login, is_superuser, member_of FROM system_auth.roles WHERE role='john';
 role | can_login | is_superuser | member_of
------+-----------+--------------+-----------
 john |      True |        False |          []

(1 rows)

To disable login privileges for john, run the following command.

cassandra@cqlsh> ALTER ROLE john WITH LOGIN = false;

You can verify this as follows.

cassandra@cqlsh> SELECT role, can_login, is_superuser, member_of FROM system_auth.roles WHERE role='john';
 role | can_login | is_superuser | member_of
------+-----------+--------------+-----------
 john |     False |        False |          []

(1 rows)

Trying to login as john using cqlsh will throw the following error.

$ cqlsh -u john
Password:
Connection error:
  ... message="john is not permitted to log in"

To re-enable login privileges for john, run the following command.

cassandra@cqlsh>  ALTER ROLE john WITH LOGIN = true;

6. Change default admin credentials

It is highly recommended to change at least the default password for the superadmin user in real world deployments to keep the database cluster secure.

As an example, let us say we want to change the cassandra user's password from cassandra to new_password. You can do that as follows:

cassandra@cqlsh> ALTER ROLE cassandra WITH PASSWORD = 'new_password';

Connecting to the cluster with the default password would no longer work:

$ bin/cqlsh -u cassandra -p cassandra
Connection error:
  ... Provided username cassandra and/or password are incorrect ...

You can now connect to the cluster using the new password:

$ cqlsh -u cassandra -p new_password

7. Deleting a user

You can delete a user with the DROP ROLE command.

For example, to drop the user john in the above example, run the following command as a superuser:

cassandra@cqlsh> DROP ROLE IF EXISTS john;

You can verify that the john role was dropped as follows:

cassandra@cqlsh> SELECT role, can_login, is_superuser, member_of FROM system_auth.roles;
 role      | can_login | is_superuser | member_of
-----------+-----------+--------------+-----------
     admin |      True |         True |          []
 cassandra |      True |         True |          []

(2 rows)

Overview

YEDIS authentication is based on passwords. Each client connecting using the YEDIS API should provide a valid password in order to execute any command successfully.

NOTE: YEDIS implements a password-only authentication scheme. From the Redis security docs page ("Authentication feature" section), Open-source Redis does not try to implement Access Control, it provides a tiny layer of authentication that is optionally turned on editing the redis.conf file.

1. Enable YEDIS authentication

You can enable access control to enforce password based authentication in YEDIS API using the CONFIG command.

To do so, connect to the cluster using redis-cli and run the following command:

127.0.0.1:6379> CONFIG SET requirepass "password"
"OK"

2. Connect with redis-cli

Next exit redis-cli, connect to the cluster again using redis-cli and run the PING command (or any other command).

127.0.0.1:6379> PING
(error) NOAUTH PING: Authentication required.

You would need to authenticate the client (redis-cli in this case) by running the AUTH command:

127.0.0.1:6379> AUTH password
"OK"

Subsequently, running any command would succeed:

127.0.0.1:6379> PING
PONG

3. Changing authentication credentials

YEDIS allows for multiple passwords (up to 2) to be accepted. This enables performing a graceful change of password without experiencing any application outage. Note that this requires knowing the old password.

Let us assume that the old password is old-password and the new password we intend to change it to is new-password. The preferred sequence is:

  • Add a new password
127.0.0.1:6379> CONFIG SET requirepass "old-password,new-password"

This enables connecting to the database using both passwords.

  • Change password used by the application tier

This would involve changing the config or pushing an updated binary to the application tier so that it now connects using new-password.

  • Drop old password
127.0.0.1:6379> CONFIG SET requirepass "new-password"
Ask our community
  • Slack
  • Github
  • Forum
  • StackOverflow
Yugabyte
Contact us

Copyright © 2017-2020 Yugabyte, Inc. All rights reserved.