# Register a Teradata Connection

{% hint style="info" %}
**Public preview**: This integration is available to all accounts that request to enable it for their tenant. Contact your Immuta representative to enable it.
{% endhint %}

## Requirement <a href="#requirement" id="requirement"></a>

* Teradata VantageCloud or Teradata VantageCore

### Permissions <a href="#permissions" id="permissions"></a>

The user registering the connection must have the permissions below.

* `APPLICATION_ADMIN` Immuta permission
* The Teradata user registering the connection must have access to the user `DBADMIN`
* The Teradata user running the setup script must have the following permission:
  * `CREATE DATABASE`

## Create the database user <a href="#create-the-database-user" id="create-the-database-user"></a>

1. ​[Create a new user in Teradata to serve as the Immuta system account](https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/Database-Administration/Working-with-Users-Roles-and-Profiles-Operational-DBAs/Working-with-Database-Users/Creating-Users). Immuta will use this system account continuously to crawl the connection.
2. ​[Grant this account the following Teradata privileges](https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/Database-Administration/Working-with-Users-Roles-and-Profiles-Operational-DBAs/Granting-Privileges-Directly-To-Users):
   1. `SELECT` on the DBC database
   2. `CREATE ROLE`
   3. `DROP ROLE`
   4. `SELECT WITH GRANT OPTION` on all Teradata views and databases that Immuta should manage permissions to
   5. `CREATE VIEW WITH GRANT OPTION`
   6. `DROP VIEW WITH GRANT OPTION`

## Configure Teradata

If your base tables are in a different database than your views, then you must grant your view database the ability to select from your base table database.

```sql
GRANT SELECT ON base_table_database TO view_database WITH GRANT OPTION;
```

## Register a Teradata connection

1. In Immuta, click <i class="fa-database">:database:</i> **Data** and select **Connections** in the navigation menu.
2. Click the **+ Add Connection** button.
3. Select the **Teradata** tile.
4. Enter the host connection information:
   1. **Display Name:** This is the name of your new connection. This name will be used in the API (`connectionKey`), in data source names from the host, and on the connections page. Avoid the use of periods (`.`) or [restricted words](#user-content-fn-1)[^1] in your connection name.
   2. **Hostname**: Your Teradata host (e.g., `your-host.env.teradata.com` ).
   3. **Port**: Port configured for Teradata.
   4. **SSL Mode**: Use the dropdown to select your SSL mode.
   5. **SSL Protocol**: Based on your SSL mode selection, also select the protocol.
5. Select the authentication method from the dropdown:
   1. **Username and Password** or **LDAP**: Enter the **username** and **password** of the [Teradata user you created above](#create-the-database-user).
   2. **OAuth**: Enter the authentication details of the [Teradata user you created above](#create-the-database-user).
      1. Fill out the **Client ID**, which is the subject of the generated token. It is also known as `sub` (subject).
      2. Fill out the **Client Secret**.
      3. Fill out the **Authority URL** of your identity provider.
      4. Enter the **Scope** to limit the operations and roles allowed in Teradata by the access token. See the [OAuth 2.0 documentation](https://oauth.net/2/scope/) for details about scopes.
6. Run the below script in your Teradata environment to create the Immuta databases and complete setup.

```
`CREATE DATABASE immuta AS PERM = 1000000000, SPOOL = 500000000, TEMPORARY = 200000000, NO FALLBACK, NO BEFORE JOURNAL, NO AFTER JOURNAL`,
`CREATE DATABASE immuta_views FROM immuta AS PERM = 100000000, SPOOL = 500000000, TEMPORARY = 200000000, NO FALLBACK, NO BEFORE JOURNAL, NO AFTER JOURNAL`,
            `CREATE TABLE immuta.immuta_profiles (
                immuta__userid VARCHAR(128) NOT NULL,
                immuta__systemid INTEGER NOT NULL,
                immuta__project INTEGER,
                immuta__project_joins BYTEINT DEFAULT 0,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                PRIMARY KEY (immuta__userid),
                UNIQUE (immuta__systemid)
            )`,
            `CREATE TABLE immuta.immuta_groups (
                immuta__systemid INTEGER NOT NULL,
                immuta__group VARCHAR(256) NOT NULL,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                PRIMARY KEY (immuta__systemid, immuta__group)
            )`,
            `CREATE TABLE immuta.immuta_authorizations (
                immuta__systemid INTEGER NOT NULL,
                immuta__key VARCHAR(256) NOT NULL,
                immuta__value VARCHAR(256) NOT NULL,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                PRIMARY KEY (immuta__systemid, immuta__key, immuta__value)
            )`,
            `CREATE TABLE immuta.immuta_purposes (
                immuta__systemid INTEGER NOT NULL,
                immuta__purpose VARCHAR(256) NOT NULL,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
                PRIMARY KEY (immuta__systemid, immuta__purpose)
            )`,
            // Granting SELECT WITH GRANT OPTION on entitlement tables to PUBLIC is required when
            // granting permissions on views that reference these tables. Since grants are made to
            // roles (not users) and Teradata doesn't allow WITH GRANT OPTION to roles, we grant
            // to PUBLIC so the system user has the necessary permissions.
            `GRANT SELECT ON immuta.immuta_profiles TO PUBLIC WITH GRANT OPTION`,
            `GRANT SELECT ON immuta.immuta_groups TO PUBLIC WITH GRANT OPTION`,
            `GRANT SELECT ON immuta.immuta_authorizations TO PUBLIC WITH GRANT OPTION`,
            `GRANT SELECT ON immuta.immuta_purposes TO PUBLIC WITH GRANT OPTION`,
        ];
```

7. Click **Save connection**.

## Grant the `immuta_views` database access

After you register the connection and the `immuta_views` database is created, you must grant that database the ability to select from the databases that have your tables and views:

```sql
GRANT SELECT ON base_table_database TO immuta_views WITH GRANT OPTION;
GRANT SELECT ON view_database TO immuta_views WITH GRANT OPTION;
```

## Map users

**Requirement**: `USER_ADMIN` Immuta permission

Map Teradata usernames to each Immuta user account to ensure Immuta properly enforces policies.

The instructions below illustrate how to do this for individual users, but you can also configure user mapping in your [IAM connection on the app settings page](https://documentation.immuta.com/saas/people/users-index/how-to-guides/external-user-mapping#configure-external-user-id-mapping-on-app-settings-page).

1. Click **People** and select **Users** in the navigation menu.
2. Click the user's **name** to navigate to their page and scroll to the **External User Mapping** section.
3. Click **Edit** in the **Teradata User** row.
4. Select the **User Type** from the dropdown:
   1. **Teradata Username**: Enter the user's Teradata username.
   2. **Unset (fallback to Immuta username)**: When selecting this option, the Teradata username is assumed to be the same as the Immuta username.
   3. **None (user does not exist in Teradata)**: Select this option if this is an Immuta-only user. This option will improve performance for Immuta users who do not have a mapping to Teradata users and will be automatically selected by Immuta if an Immuta user is not found in Teradata. To ensure your Teradata users have policies correctly applied, manually map their usernames using the first option above.
5. Click **Save**.

[^1]: Your display name cannot be any of the following words: `data`, `connection`, `object`, `crawl`, `search`, `settings`, `metadata`, `permission`, `sync`, `bulk`, and `upgrade`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/saas/configuration/integrations/teradata/register-a-teradata-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.