This document applies to environments that have upgraded Cyral from version 2.15 or earlier to version 2.16 or later, and in particular those that use SSO authentication. Cyral 2.16 introduced identity maps in Cyral (moving SSO identity mapping logic to the Cyral Control Plane; you no longer need to manage these mappings in your external secrets manager). This release also made changes to some authentication and logging controls. 

After the upgrade of the Cyral control plane, your pre-upgrade configuration will be preserved in the upgraded control plane. To complete the upgrade, there are a few configuration changes you must carry out to ensure your existing repositories will continue to be monitored and protected as they were before the upgrade. Below, we explain the changes you need to make.

Upgrade your repo settings for authentication and logging

For each repository, go to the Data Repos section of the Cyral control plane UI, click on the repo's name, and go to the Advanced tab. Here, make the following settings:

1. Choose your Identity Provider from the drop-down box.

2. Unselect the checkbox Allow native authentication.

   1. Note: If you prefer to give users the choice of accessing the same repo using either SSO or native credentials, then select Allow native authentication. If you choose to offer users this choice, then when connecting as an SSO user, the person must include their SSO username in their connection string, prefixed with "idp:". For example, the username portion of the connection string might be: idp:nancy.drew@hhiu.us. Without the "idp:" prefix, Cyral assumes the login is a database-native authentication attempt.

Check your log settings

In Log Settings: Volume Settings, choose the appropriate log level settings. The options have changed.

Upgrade your database SSO credentials and identity mappings

Before Cyral version 2.16, mapping of SSO groups to database-native accounts ("local accounts") was done by saving secrets in your AWS Secrets Manager and then registering that secret using the Cyral Integrations page. Cyral 2.16 introduces identity maps in Cyral, which moves the mapping logic to the Cyral Control Plane. When using 2.16 or later sidecars, you will save a simple username/password blob in your AWS Secrets Manager and provide the ARNs of those blobs (one per local account) when you configure the repository for SSO in the Data Repos panel of the Cyral Control Plane.

As a result, any pre-2.16 secrets manager payloads in your environment are incompatible with any version 2.16 or later sidecars you deploy. 

More details on this can be found in Authenticate repository access with SSO.

Procedure

For each repository whose sidecar has been upgraded to 2.16 or later, you must perform these upgrade steps if the repository is set up for SSO authentication:

1. Create or upgrade each credential blob. For each local account you will use, create a database credential JSON blob in AWS Secrets Manager. The JSON blob must contain only the username and password of the local account. Place the secret at any key location with the prefix /cyral/dbsecrets/. For example: 

2. Register each local account in Cyral. First, from AWS Secrets Manager, copy the ARN of the local account credentials. In Cyral, go to Data Repos, click Local Accounts, and click Track Account. In the Track Account form, enter the account username. This represents the name of the local account in the repository. Choose AWS Secrets Manager as your manager type, and paste the ARN for the local account credentials. Inside the ARN, the secret must start with the /cyral/dbsecrets prefix. Click Track. 

Below we show local account creation for “analyst” 

3. Map each SSO user or group to a local account. When a user authenticates, they can be mapped to a local account based on their username, or based on their membership in an SSO group. Set up each mapping as follows: In Cyral's Data Repos page, click Identity to Account Map and click the plus sign. Choose User or Group as the identity type. In the Identity field, specify the SSO user name or group name as it's written in your identity service. In the Local Account field, choose the name of the local account you configured earlier. In the Duration field, set a length of validity for the access, or click Unlimited to grant access that will not expire automatically. Click Create.

Below is a screenshot that shows the SSO group, “Data Analysts,” being mapped to the local account, “analyst”.

4. Remove unneeded secrets integrations. After this upgrade, the sidecar no longer needs the AWS Secrets Manager integration you used before the upgrade. On the Integrations page, you can delete unneeded integration by setting the AWS region to be None as shown in the screenshot that follows.