Skip to main content
Version: v4.1

Connect to a repository

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

Connection string reference​

Most connection strings include the following fields:

  • SIDECAR_ENDPOINT is the hostname or IP address of the Cyral sidecar for the repository. We use an example value, sidecar.example.com.
  • SIDECAR_LISTENING_PORT is where the sidecar listens for connections. We use an example value, 3306.
  • SSO_USER is the username of the person trying to connect to the data repository, as recorded in the enterprise identity management system. In examples, we use bwilliams@barnfeed.com
  • DATABASE_ACCOUNT is the person's user name in the repository. In examples, we use dataScienceUser.
  • AUTH_TOKEN is the user's authentication token generated by Cyral. In examples, we use MDE4BQFZNh9T0BhTXkvc2zJdx5bLLLT-.

Optional connection string fields:

  • DATABASE_NAME is the name of the database. In examples, we use feed_survey.
  • REPO_NAME is the name of the repository in Cyral that tracks your database. In examples, we use mysql_feed_repo.
  • MongoDB connections require an AUTH_DATABASE_NAME. In examples, we use admin.

Connect to a data repository with native credentials​

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 Cyral control plane UI as shown below.

Here, the sidecar endpoint address is comprised of the sidecar host address and the listening port associated with the repository, formatted as {SIDECAR_ENDPOINT}:{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 sidecar.example.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_ENDPOINT} -P {SIDECAR_LISTENING_PORT} -u {DATABASE_USER} -p{DATABASE_PASSWORD} -ssl-mode=REQUIRED

Example:

mysql -h sidecar.example.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 access rules have 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 database 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 the Cyral CLI for obtaining the access token on the command line. For details, see Using the Cyral CLI.

    Please note that the older CLI tool gimme_db_token is deprecated and will stop working with a future version of the Cyral Control Plane.

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 sidecar.example.com -P 3306 --default-auth=mysql_clear_password --enable-cleartext-plugin --ssl-mode=REQUIRED

Users with multiple matching access rules: If your SSO user might be mapped to more than one database account in the database, then you need to specify which database account to use. You can do this in the -u flag by providing both user account names in the format: {SSO_USER}:{DATABASE_ACCOUNT}.

mysql -u "{SSO_USER}:{DATABASE_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 DATABASE_ACCOUNT value:

mysql -u "bwilliams@barnfeed.com:dataScienceUser" -pMDE4BQFZNh9T0BhTXkvc2zJdx5bLLLT- -h sidecar.example.com -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!

Smart Port connection instructions​

When connecting through a Cyral Smart Port, you must include the repository name in the connection string.

MySQL connections through a Smart Port​

A sidecar smart port offers connections to multiple repositories, so when you connect, you must specify which repository you want to connect to. You have the following options for including the repository name:

  • in the username field
  • in the database name field
  • in a custom connection attribute

See the instructions for each option, below.

Supply the repository name in the username field for MySQL​

When connecting with the MySQL CLI, you can supply the repository name in the -u (username) field. Add the repository name in one of the following ways:

The following options are available for an SSO user. The prefix "idp:" is a Cyral-required part of the username for any repository that supports both SSO and native authentication.

-u idp:{SSO_USER}:{REPO_NAME}

or

-u idp:{SSO_USER}:{REPO_NAME}:{DATABASE_ACCOUNT}

The following options are available if you have disallowed native authentication on the repository. If you have disallowed native authentication, you can omit the "idp:" prefix as shown here. For an SSO user:

-u{SSO_USER}:{REPO_NAME}

or

-u{SSO_USER}:{REPO_NAME}:{DATABASE_ACCOUNT}

The following option is for native authentication only:

-u{DATABASE_ACCOUNT}:{REPO_NAME}

Supply the repository name in the database name field for MySQL​

When connecting with the MySQL CLI, you can supply the repository name in the -D (database name) field. Add the repository name by appending ":{REPO_NAME}" to the MySQL database name. The format of the -D field is:

-D{DATABASE_NAME}:{REPO_NAME}

For example, the -D field might look like: 

-Dfeed_survey:mysql_feed_repo

assuming a database called feed_survey in MySQL and Cyral set to track the MySQL repository as mysql_feed_repo.

Supply the repository name in a custom connection attribute for MySQL​

When connecting with a driver such as the MySQL JDBC driver, you can supply the repository name in a custom connection attribute. For example, with the MySQL JDBC driver, specify the connectionAttributes connection property as:

prop.put("connectionAttributes", "cyral.reponame:{REPO_NAME}");),

replacing {REPO_NAME} with your repository's name as saved in Cyral.

PostgreSQL connections through a Smart Port​

When connecting through a Smart Port, include the repository name.

A sidecar smart port offers connections to multiple repositories, so when you connect, you must specify which repository you want to connect to. You have the following options for including the repository name:

  • in the username field
  • in the database name field
  • in the PGOPTIONS attribute

See the instructions for each option, below.

Supply the repository name in the username field for PostgreSQL​

When connecting with a CLI client, you can supply the repository name in the -u (username) field. Add the repository name in one of the following ways:

The following options are available for an SSO user. The prefix "idp:" is a Cyral-required part of the username for any repository that supports both SSO and native authentication.

-U idp:{SSO_USER}:{REPO_NAME}

or

-U idp:{SSO_USER}:{REPO_NAME}:{DATABASE_ACCOUNT}

The following options are available if you have disallowed native authentication on the repository. If you have disallowed native authentication, you can omit the "idp:" prefix as shown here. For an SSO user:

-U {SSO_USER}:{REPO_NAME}

or

-U {SSO_USER}:{REPO_NAME}:{DATABASE_ACCOUNT}

Supply the repository name in the database name field for PostgreSQL​

When connecting with a CLI client, you can supply the repository name in the -d (database name) field. Add the repository name by appending ":{REPO_NAME}" to the database name. The format of the -d field is:

-d {DATABASE_NAME}:{REPO_NAME}

For example, the -D field might look like: 

-d feed_survey:mysql_feed_repo

assuming a database called feed_survey and Cyral set to track the repository as mysql_feed_repo.

Supply the repository name in the PGOPTIONS attribute for PostgreSQL​

When connecting with a command-line PostgreSQL client, you can supply the repository name in the PGOPTIONS attribute. Add the property using this format:

-PGOPTIONS=" -c cyral.reponame={REPO_NAME}"

replacing {REPO_NAME} with your repository's name as saved in Cyral.

Redshift connections through a Smart Port​

When connecting through a Smart Port, include the repository name.

A sidecar smart port offers connections to multiple repositories, so when you connect, you must specify which repository you want to connect to. You have the following options for including the repository name:

  • in the username field
  • in the database name field
  • in the PGOPTIONS attribute

See the instructions for each option, below.

Supply the repository name in the username field for Redshift​

When connecting with a CLI client, you can supply the repository name in the -u (username) field. Add the repository name in one of the following ways:

The following options are available for an SSO user. The prefix "idp:" is a Cyral-required part of the username for any repository that supports both SSO and native authentication.

-U idp:{SSO_USER}:{REPO_NAME}

or

-U idp:{SSO_USER}:{REPO_NAME}:{DATABASE_ACCOUNT}

The following options are available if you have disallowed native authentication on the repository. If you have disallowed native authentication, you can omit the "idp:" prefix as shown here. For an SSO user:

-U {SSO_USER}:{REPO_NAME}

or

-U {SSO_USER}:{REPO_NAME}:{DATABASE_ACCOUNT}

Supply the repository name in the database name field for Redshift​

When connecting with a CLI client, you can supply the repository name in the -d (database name) field. Add the repository name by appending ":{REPO_NAME}" to the database name. The format of the -d field is:

-d {DATABASE_NAME}:{REPO_NAME}

For example, the -D field might look like: 

-d feed_survey:mysql_feed_repo

assuming a database called feed_survey and Cyral set to track the repository as mysql_feed_repo.

Supply the repository name in the PGOPTIONS attribute for Redshift​

When connecting to Redshift with a command-line PostgreSQL client, you can supply the repository name in the PGOPTIONS attribute. Add the property using this format:

-PGOPTIONS=” -c cyral.reponame={REPO_NAME}”

replacing {REPO_NAME} with your repository's name as saved in Cyral.

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_ENDPOINT}])(PORT=[{SIDECAR_LISTENING_PORT}]))(CONNECT_DATA=(SID=ORCL)))

where:

  • SIDECAR_ENDPOINT is the 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_ENDPOINT}])(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}:{DATABASE_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

If Client TLS is turned on for the database, follow the instructions in Set up clients for TLS connections, below.

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_ENDPOINT}])(PORT=[{SIDECAR_LISTENING_PORT}]))(CONNECT_DATA=(SID=ORCL)))

where:

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

If Client TLS is turned on for the database, follow the instructions in Set up clients for TLS connections, below.

Set up clients for TLS connections​

If client TLS is enabled for your Oracle database, 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_DOMAIN/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.