Skip to main content

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 respository, 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 -p V8j5k_aW

Connect to a data repository with SSO credentials#

  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

Example:

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

Note: If multiple identity maps apply to your user, declare {SSO_USER}:{LOCAL_ACCOUNT} as the DB user to specify which local account you'll use to log in:

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" -p MDE4BQFZNh9T0BhTXkvc2zJdx5bLLLT- -h 35.194.11.53 -P 3306 --default-auth=mysql_clear_password --enable-cleartext-plugin --ssl-mode=REQUIRED

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

  2. Connect to S3 as usual. 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.

Connecting a SQL*PLUS client:#

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

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>:8000/v1/templates/ca_bundle> -o cyral_ca_bundle.pem
  2. 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.