Authentication and authorization

Systems establish authentication first, followed by authorization if implemented.

Authentication types

Authentication is the act of validating that users are who they claim to be. Two methods of authentication are common:

Passwords: If a user enters the correct credentials, the system assumes their identity is valid and grants access.
Authentication apps: Generate security codes via a third-party app to grant access.

Astra DB Classic supports single sign-on with multiple identity providers:

Google: Use your Gmail or a G-Suite account to authenticate.
GitHub: Use your GitHub account to authenticate.
SAML: Use any SAML 2.0 capable Identity Provider (IdP) to authenticate. These include Microsoft Entra ID, Okta, OneLogin, Google, and Ping Identity. For more, see the SSO Documentation.

Existing Astra DB Classic users

If you use GitHub for authentication and have the keep my email addresses private option enabled, you must:

Make your email public and change your password to switch to Astra DB Classic local authentication.

OR
Opt for a different IdP linked to the same email.

New Astra DB Classic users

If you are registering with GitHub and have a private email, you must either make it public or choose an alternative authentication method.

What is authorization?

Authorization is the process of giving a user permission to access a specific resource or function. Other terms for this functionality are access control or client privilege.

Users must authenticate before Astra DB Classic will authorize them. Authorization is generally controlled by the organization’s administrators.

Use an application token to authorize Astra DB Classic connection

Authorize your application’s connection to your Astra DB Classic database using an application token.

Create this token from either the Astra Portal or the DevOps API.

Methods for accomplishing with Astra DB

Astra DB uses an authentication and authorization method, JSON web token (JWT) using open policy agent (OPA). The workflow below shows how this method bypass Stargate using the Astra Authenticator, Astra IAM. All queries are then sent to DSE to handle the authentication and authorization.

If you are using the Advanced Workloads, the advanced workload queries (i.e. search and graph queries) can be sent directly to Astra DB Classic. The authentication and authorization is performed by the authenticator and authorizer module using OPA.

Table-based authentication/authorization

Table-based authentication and authorization uses the Stargate Auth API to generate an auth token based on a Cassandra username and password. The auth-table-based-service uses the generated auth token to allow Stargate API queries access to the Cassandra data.

By default, the token persists for 30 minutes with a sliding window. Each use of the token to authenticate resets the 30 minute window. A token created and used after 29 minutes will authenticate a request, but if 31 minutes passes before use, the token will no longer exist.

The length of time to persist the token is configurable using the system property stargate.auth_tokenttl. For example, set the token to persist for 100 seconds:

JAVA_OPTS='-Dstargate.auth_tokenttl=100' ./starctl \
--developer-mode --cluster-name test --cluster-version 3.11 --enable-auth

The step below uses cURL to access the REST interface to generate the needed token.

Generate an auth token

First generate an auth token that is required in each subsequent request in the X-Cassandra-Token header.

curl -L -X POST 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v1/auth' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "username": "$CLIENT_ID",
    "password": "$CLIENT_SECRET"
}'

You should receive a token in the response.

{"authToken":"{auth-token}"}

The authorization token returned must be either exported as an environment variable (cURL commands with REST or Document API) or entered into the HTTP Header (GraphQL mutations).

REST or Document API(/v2)
GraphQL

Store the auth token in an environment variable to make it easy to use with cURL.

export AUTH_TOKEN={auth-token}

Add the auth token to the HTTP Headers box in the lower lefthand corner of the GraphQL playground:

{
  "X-Cassandra-Token":"bff43799-4682-4375-99e8-23c8a9d0f304"
}