Skip to main content
Version: v4.0

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 Cyral's CLI token retriever for SSO, gimme_db_token. For details, see CLI Token retriever for SSO, below.

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.

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_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.