Skip to main content
Version: v2.x

Connect to a repository

Users can connect to data repositories through Cyral using native credentials as well as SSO credentials.

Connect to a data repository with native credentials​

note

If the repo you're looking for is not available in Cyral, follow the quickstart steps to set it up.

To access a data repository through Cyral, you'll connect to its sidecar endpoint instead of directly to its true endpoint. Once you've assigned a repository to a sidecar, you can find the sidecar endpoint associated with that repository in the Data Repos tab of the Sidecars screen in the Management Console as shown below. Here, the sidecar endpoint is comprised of the sidecar host address and the listening port associated with the repository, formatted as {SIDECAR_HOST}:{SIDECAR_LISTENING_PORT}.

Connect to your repository through the sidecar using your usual client, but replacing the repository host and port with the sidecar host and listening port displayed in the management console.

Below we show examples for connecting to a repository through a sidecar using native credentials. In these examples, the sidecar has host address sidecar01.hhiu.cyral.com and the listening port varies based on the repository type (MySQL: 3306, PostgreSQL: 5432, MongoDB: 27017, Oracle: 1521). In all cases, we're connecting as the native user bob with password V8j5k_aW, and we're accessing the invoices database. For MongoDB, we assume the auth database is called admin.

Connection syntax and examples using native credentials​

Syntax:

mysql -h {SIDECAR_HOST} -P {SIDECAR_LISTENING_PORT} -u {DATABASE_USER} -p{DATABASE_PASSWORD} -ssl-mode=REQUIRED

Example:

mysql -h sidecar01.hhiu.cyral.com -P 3306 -u bob -pV8j5k_aW
caution

Do not include a space between the -p flag and the authentication token value!

Connect to a data repository with SSO credentials​

note

This requires that an IdP integration has been configured and SSO authentication has been configured for the repository you wish to access.

  1. Navigate to the Cyral access portal, or click the Your Access Token button at the top of the Cyral control plane UI.

  2. Find your repository in the list and click the Connect button.

    tip

    If you don't see the repository you're looking for, click the Request access to a data repository button and choose the name of the repository and the local account (native account in the repository) you wish to use to access it. Specify a desired Duration of access and click Submit.

    tip

    If you're a Cyral administrator and the repo you're looking for is not listed in the Request access screen, see the quickstart to set it up.

  3. A dialog appears showing connection information for your repository. Use the copy button to copy the connection string or URI that's appropriate for your client. Note that when you connect to a data repository through Cyral, you'll use its sidecar endpoint address instead of the data repository's native address.

    info

    If you work at the command line, there's a faster way to get your token! Use Cyral's CLI token retriever for SSO, gimme_db_token. For details, see CLI Token retriever for SSO, below.

Connection string reference​

The following examples show how an SSO-authenticated user connects to a repository through the Cyral sidecar. In these examples:

  • SIDECAR_ENDPOINT is the IP address of the Cyral sidecar for the repository. Our example runs at 35.194.11.53.
  • SIDECAR_LISTENING_PORT is where the sidecar listens for connections. Our example uses port 3306.
  • SSO_USER is the user name of the person trying to connect to the data repository), as recorded in the enterprise identity management system. For this example, we use bwilliams@barnfeed.com
  • LOCAL_ACCOUNT is the person's user name in the repository. For this example, we use dataScienceUser.
  • AUTH_TOKEN is the user's authentication token generated by Cyral. Our example token is MDE4BQFZNh9T0BhTXkvc2zJdx5bLLLT-.
  • Where needed, we show an example DATABASE_NAME of feed_survey.
  • For MongoDB, our example AUTH_DATABASE_NAME is admin.

SSO connection syntax and examples​

caution

If Allow native authentication is enabled for the repository, please prefix SSO_USER with the required idp: prefix (e.g.idp:bwilliams@barnfeed.com). This prefix is used to distinguish between SSO credentials and native credentials.

The following examples assume that Allow native authentication is not enabled, so you'll see that we don't use an idp: prefix here.

Syntax:

mysql -u "{SSO_USER}" -p{AUTH_TOKEN} -h {SIDECAR_ENDPOINT} -P {SIDECAR_LISTENING_PORT} --default-auth=mysql_clear_password --enable-cleartext-plugin --ssl-mode=REQUIRED
caution

Do not include a space between the -p flag and the authentication token value!

Example:

mysql -u "bwilliams@barnfeed.com" -pMDE4BQFZNh9T0BhTXkvc2zJdx5bLLLT- -h 35.194.11.53 -P 3306 --default-auth=mysql_clear_password --enable-cleartext-plugin --ssl-mode=REQUIRED

What about users with multiple identity maps? If your SSO user might be mapped to more than one local account in the database, then you need to specify which local account to use. You can do this in the -u flag by providing both user account names in the format: {SSO_USER}:{LOCAL_ACCOUNT}.

mysql -u "{SSO_USER}:{LOCAL_ACCOUNT}" -p{AUTH_TOKEN} -h {SIDECAR_ENDPOINT} -P {SIDECAR_LISTENING_PORT} --default-auth=mysql_clear_password --enable-cleartext-plugin --ssl-mode=REQUIRED

Example with a LOCAL_ACCOUNT value:

mysql -u "bwilliams@barnfeed.com:dataScienceUser" -pMDE4BQFZNh9T0BhTXkvc2zJdx5bLLLT- -h 35.194.11.53 -P 3306 --default-auth=mysql_clear_password --enable-cleartext-plugin --ssl-mode=REQUIRED
caution

Do not include a space between the -p flag and the authentication token value!

Connect to a data repository using TLS​

note

The instructions in this section are valid for all repository types for sidecar versions up to v2.30.x. For sidecar versions greater or equal to v2.31.0, these instructions are exclusive for DynamoDB and S3 repositories.

Since v2.31.0, the sidecar can use different certificates to enable TLS communication as described in Certificates for sidecars. For these sidecars, you need to make sure that the CA used to sign the sidecar certificate is added to your list of trusted CAs. This CA will not be the same as the one obtained from the instructions below.

If Client TLS option is enabled for your repository, you must set up the Cyral CA certificate for each client that will connect. Follow these steps:

  1. Download the Cyral CA certificate bundle from the Cyral control plane using the following API call:

    curl https://<CYRAL_CONTROL_PLANE>:8000/v1/templates/ca_bundle -o cyral_ca_bundle.pem
    caution

    The ca_bundle contains both a Root CA and Intermediate CA certificate. You will need to make sure you import both of these certificate files into your trusted CA store.

    Some tools such as orapki are not able to import a bundle containing multiple certificates. In these cases, you will need to split this bundle into two files and import each file individually into your trusted CA store.

  1. Add the Cyral CA certificate to your client. Here are two common client setups:

    • For a Java client (like JDeveloper) you will add it to the key store. The key store location depends on Java or client installation. For example, if you're running JDeveloper on Linux installed under the local user's account, the file typically resides at ~/Oracle/Middleware/Oracle_Home/oracle_common/jdk/jre/lib/security/cacerts. Use keytool to import the certificate. For example:

      keytool -import -alias cyral-root -keystore <cacerts> -file cyral_ca_bundle.pem -storepass changeit

    • For a SQL*Plus client, follow the instructions provided by AWS, Configuring SQL*Plus to use SSL with an Oracle DB instance.

CLI token retriever for SSO​

For command line users, Cyral offers the Cyral CLI token retriever for SSO, a tool to simplify the SSO login experience. This CLI token retriever provides an alternative to the manual process of visiting the Cyral management console and getting a token through the Copy Token button.

When a user wants to connect, the token retriever directs them to the Cyral portal to authenticate with their SSO credentials. Upon successful authentication, the tool generates a token that's valid for 24 hours on the data endpoints the user has access to.

Install the CLI token retriever for SSO​

Prerequisites: You must have completed SSO setup in your SSO platform, as explained in the section, Authenticate repository access with SSO.

Procedure​

Install the Cyral SSO token retriever for each user as follows:

  1. Install the CLI tool, gimme_db_token on the database user’s machine using either brew or pip3. Type one of the following in your command shell:
    brew install cyral-gimme-db-token
    or
    pip3 install cyral-gimme-db-token
  2. Share the appropriate connection instructions below with the database user.

Using the CLI token retriever for SSO (basic mode)​

The CLI token retriever's basic mode works for all supported data endpoint types. After you authenticate successfully, the retriever returns a database access token to the terminal console. Using this mode, you can run the tool and copy the token from your console, or you can assign the token value to a shell environment variable.

The syntax for basic mode is:

export CYRAL_TOKEN=$(gimme_db_token --address <your_Cyral_service_address> --stdout --silent)

where:

  • the --address flag supplies your Cyral service address, which is similar to the URL of your Cyral control plane, for example, acme.cyral.com
  • --stdout returns the token to standard out
tip

If your site uses more than one IdP please note: If your Cyral SSO installation offers multiple identity providers (IdPs) to choose from, you can pass the --idp flag with the name of the IdP you wish to use. See Pass an IdP hint to the CLI token retriever for details.

Connect to PostgreSQL using the CLI token retriever​

Cyral allows you to use your single sign-on (SSO) credentials to connect to a PostgreSQL database. SSO logins rely on an expiring SSO token you can get from the Cyral login portal or from the gimme_db_token tool.

  1. To get your database login token, open a terminal session, and run the following, using the --address flag to provide your Cyral service address, which is similar to the URL of your Cyral control plane, for example, acme.cyral.com

    gimme_db_token pg  --address <your_Cyral_service_address>

  2. If you're not already logged in to a database SSO session, a browser tab will open automatically and prompt you to provide your SSO credentials in the Cyral login portal. (If you're not prompted, it means you already have a valid Cyral SSO session.)

    The tool automatically inserts a token into your PostgreSQL credentials file (the .pgpass file).

  3. Start a database session as usual. PostgreSQL uses your Cyral-provided credentials to log you in.

If your authentication fails, it’s likely your SSO token has expired. By default, each token expires 24 hours after it's issued. Run the gimme_db_token tool again to generate a fresh token.

Connect to S3 data using the CLI token retriever​

Cyral allows you to use your single sign-on (SSO) credentials to connect to your data in S3. SSO logins rely on an expiring SSO token you can get from the Cyral login portal or from the gimme_db_token tool.

  1. Before you use the AWS CLI to access S3, it is required to install some prerequisites. The gimme_db_token tool will install them on the first run and for that you just need to open a terminal session and run the following, using the --address flag to provide your Cyral service address, which is similar to the URL of your Cyral control plane, for example, acme.cyral.com:

    gimme_db_token s3 --address <your_Cyral_service_address> --sidecar <sidecar_address:port> --profile <your AWS profile name> --autoconfigure

    where

    • the --address flag supplies your Cyral service address, which is similar to the URL of your Cyral control plane, for example, acme.cyral.com
    • the --sidecar flag supplies your Cyral sidecar address and port, for example, mysidecar.cyral.com:453.
    • the --profile flag specifies your AWS profile name. The token tool automatically inserts a token into your AWS credentials file (usually ~/.aws/credentials/), saving the token in the AWS profile that you've specified.
    • the --autoconfigure flag will make sure all the necessary configurations and pre-requisites are installed to get AWS CLI to work properly with the sidecar.

    If you're not already logged in to a database SSO session, a browser tab will open automatically and prompt you to provide your SSO credentials in the Cyral login portal. (If you're not prompted, it means you already have a valid Cyral SSO session.)

  2. After all the prerequisites are installed, gimme_db_token tool can be used with less parameters to get new access tokens for AWS CLI:

    gimme_db_token s3 --address <your_Cyral_service_address> --profile <your AWS profile name>

    where

    • the --address flag supplies your Cyral service address, which is similar to the URL of your Cyral control plane, for example, acme.cyral.com
    • the --profile flag specifies your AWS profile name. The token tool automatically inserts a token into your AWS credentials file (usually ~/.aws/credentials/), saving the token in the AWS profile that you've specified.

    If you're not already logged in to a database SSO session, a browser tab will open automatically and prompt you to provide your SSO credentials in the Cyral login portal. (If you're not prompted, it means you already have a valid Cyral SSO session.)

  3. Connect to S3 as usual using the profile you informed in the command. Your Cyral-provided credentials will be used to log you in.

If your authentication fails, it’s likely your SSO token has expired. By default, each token expires 24 hours after it's issued. Run the gimme_db_token tool again to generate a fresh token.

Connect to Oracle on RDS through the Cyral sidecar​

Once an Oracle database is protected by Cyral, users connect to it with their usual database clients, as described below.

Connect a SQL*PLUS client​

Connect a SQL Developer client​

  1. In SQL Developer, click on the ➕ (plus sign) in the top left corner to add a new database connection.
  2. Fill out the highlighted fields with the connection info displayed in the Cyral Access Portal.

To learn more about connection info for Oracle, see:

Using a connect identifier for Oracle​

To connect using the Oracle SQL*PLUS client, edit the client's connect identifier. The connect identifier takes the form:

(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=[{SIDECAR_HOST}])(PORT=[{SIDECAR_LISTENING_PORT}]))(CONNECT_DATA=(SID=ORCL)))

where:

  • SIDECAR_HOST is the load balancer address of your Cyral sidecar
  • SIDECAR_LISTENING_PORT is the sidecar listener port as configured in Cyral. This is 1521 by default.

For convenience, you can add the connect identifier as a net service name entry inside a tnsnames.ora file so the connect identifier can be replaced by a name referring to the net service name. For example, if you add an entry, mydb, in tnsnames.ora like this:

mydb = (DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=[{SIDECAR_HOST}])(PORT=[{SIDECAR_LISTENING_PORT}]))(CONNECT_DATA=(SID=ORCL)))

then you can pass "mydb" when you launch SQL*PLUS, like this:

  • to log in with an SSO account:

    sqlplus '"{SSO_USER}:{LOCAL_ACCOUNT}"/{AUTH_TOKEN}@mydb'
    important

    If your SSO username contains an @ sign, as in sara@example.com, then when specifying the SSO_USER you must replace the @ with (a).

    For example:

    sqlplus '"sara(a)example.com:dataScienceUser"/bf439791ab0e27eddaca3e411fda32109@health-stats-db'

    note

    To run the above examples on Windows, omit the outer single quotes (').

  • to log in with a native Oracle account:

    sqlplus {DATABASE_USER}/{DATABASE_PASSWORD}@mydb

Note: If Client TLS option is turned on for the database, follow the instructions in Connect to a data repository using TLS.

Connecting a JDBC-based client​

To connect using a JDBC-based client, you’ll configure the client as usual and use a JDBC string formatted as follows:

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=[{SIDECAR_HOST}])(PORT=[{SIDECAR_LISTENING_PORT}]))(CONNECT_DATA=(SID=ORCL)))

where:

  • SIDECAR_HOST is the load balancer address of your Cyral sidecar
  • SIDECAR_LISTENING_PORT is the sidecar listener port as configured in Cyral. This is 1521 by default.

Note: If Client TLS option is turned on for the database, follow the instructions in Connect to a data repository using TLS.