# Set up auth credentials

An <u>**auth credential**</u> verifies one of your destinations to receive data from Redox. [Learn about receiving data from Redox](/basics/data-exchange-with-redox/receiving-data-from-redox).

## Prerequisites

- Any user can view auth credentials in a given environment, but a user must be assigned to an <u>engineer role</u> to manage them. [Learn about user roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles).
- You must have completed onboarding to Redox and implemented at least one connection.
- [Use Network Explorer](https://redoxengine.com/explore/) to see which systems Redox already integrates with. 
- If you can’t find the system you’re looking for, [review our process for adding a new system adapter](/implementation-guide/add-a-new-system-adapter-to-redox) to our network. 
- Decide which supported auth strategy to use: 
  - AWS Signature Version 4
  - Google Workload Identity Federation (WIF)
  - JWT bearer
  - OAuth 2.0 Two-Legged with secrets
  - OAuth 2.0 2-legged with JWT for GCP
  - SMART backend

## View auth credentials

1. Log in to the Redox dashboard.
2. From the navigation menu, click the **Developer** page.
3. By default, the <u>Sources</u> tab opens. Click the **Authentication** tab to view any configured auth credentials. 
4. To view a specific auth credential’s configuration details, click the **auth credential row** in the table. 

## Create an auth credential

1. Log in to the dashboard. 
2. From the navigation menu, select the **Developer** page.
3. By default, the <u>Sources</u> tab opens. Click the **Authentication** tab. 
4. All configured OAuth API keys and auth credentials display in a table. Click the **New** button \> **New auth credential** option.
5. The <u>New auth credential</u> form opens. Enter a human-readable **name** for the auth credential. This will appear in the <u>Authentication</u> table.
At any point, click the **Cancel** button to discard and exit the form.  
6. From the <u>Strategy</u> drop-down field, select the relevant **auth strategy** that the auth credential will use to verify the source’s legitimacy. 


![On the New auth credential form, a user enters a name and selects the auth strategy type.](https://images.ctfassets.net/cl3wt5ehhnlv/6KMUmV7rT0kGevcLmVjSQ7/8c07df7e7e3d6633c3c6fc86d417f9d3/auth-credential-create-new.gif)

*Select the auth strategy type*


7. More configuration fields appear, which are specific to the selected auth strategy type. 
After you start entering settings, click the **Clear** button to reset the form at any point. 


> **Tip for masked secret values in auth credentials**
>
> When pasting values into masked fields (e.g., secrets, passwords, tokens) for auth credentials, make sure you don’t accidentally copy extra whitespace in the string. Extra whitespace will result in an authentication error when trying to verify the destination.
>
> _Best practice_: Paste the value into a text editor first (between quotes) to check for extra whitespace.




<details>
<summary>AWS Signature Version 4</summary>

Fill out the necessary configuration details for this strategy type. Required fields are denoted with an asterisk in the dashboard.

Basic fields are common configuration settings. For less common configuration options, click the **Show advanced** fields button.

### Basic fields

| **Field** | **Notes** |
| --- | --- |
| Access key | The AWS access key ID provisioned for API calls to the AWS service. |
| Secret key | The AWS private key ID provisioned for API calls to the AWS service. |
| Service name | The name of the AWS cloud service to connect to. We currently support <u>Healthlake</u> or <u>S3</u>.  Typically, this field populates with the default service (i.e., `healthlake`). However, if you’re creating an auth credential within the destination wizard and you select either Databricks, Snowflake, or S3 as your <u>Product type</u>, this field automatically populates with `s3` instead. |
| AWS region | The AWS region the service is in. This field automatically populates with the default region (i.e., `us-east-1`). |

### Advanced fields

| **Field** | **Notes** |
| --- | --- |
| Session token | A session token, if using temporary credentials. |

</details>




<details>
<summary>Google Workload Identity Federation (WIF)</summary>

Fill out the necessary configuration details for this strategy type. Required fields are denoted with an asterisk in the dashboard.

| **Field** | **Notes** |
| --- | --- |
| Audience | The system that should consume the authentication credentials. |
| Delegates | The system that must provide the final access token in the authentication workflow. |
| Token lifetime | The length of time that the delegated credentials are valid, typically in number of seconds. |
| Service account scope | The scope or access granted with the authentication credentials. |
| Impersonation URL | The URL (provided by the external identity provider) that a system uses to impersonate the service account in order to get access. |
| STS scope | The scope or access granted by the Security Token Service. This field populates with the default value. |
| STS token URL | The endpoint URL for the GCP Security Token Service. This field populates with the default value. |
| Options | An additional set of features that the Security Token Service supports. |

</details>




<details>
<summary>JWT bearer</summary>

When you select <u>**JWT Bearer**</u>, you must first select the **JWT algorithm** (i.e., the supported algorithm for signing a private key) for the relevant configuration fields to appear: 

- HS256
- HS384
- HS512
- RS256
- RS384 (default)
- RS512
- PS256
- PS384
- PS512
- ES256
- ES384
- ES512

Fill out the necessary configuration details for the selected algorithm type. Required fields are denoted with an asterisk in the dashboard. Basic fields are common configuration settings. For less common configuration options, click the **Show advanced** fields button. 

### Basic fields

| **Field** | **Notes** |
| --- | --- |
| Client secret | The secret key value to authenticate the JWT. _This is only available for symmetric signing algorithms (i.e., HSXXX)._ |
| Private key | The PEM-encoded private key that will sign the JWT. _This is only available for asymmetric signing algorithms (i.e., RSXXX, PSXXX, ESXXX)._ |
| JWT key ID | The identifier of the private/public key pair used to sign the JWT. This identifier is included in the JWT header as the `kid` property. |
| Client ID | The OAuth client. This value is assigned by the authorization server and populates the sub claim in the JWT. _For GCP users_, set this value to the client email (e.g., `"clientId": "<client_email>"`). |
| Audience | The intended recipient of the access token. This is typically the URI of the resource server.  _This is only available for asymmetric signing algorithms (i.e., RSXXX, PSXXX, ESXXX)._ |

### Advanced fields

| **Field** | **Notes** |
| --- | --- |
| Client certificate | A digital certificate used to authenticate the client to the server. The client certificate proves the identity of the client in mutual TLS authentication to ensure a secure connection. |
| Client certificate key | The private key associated with the client certificate. |
| Expiration seconds | The number of seconds that the access token is valid, if used. This field is only used if the authorization server doesn't send an expiration value in the response. |
| Include x5t | A message header specific to JWT. Some systems require this header, in which case you can toggle this to ON. If not needed, toggle this to OFF. |
| Include JKU | JKU auth allows Redox to expose a URL that holds public keys for the auth credential. If you want to use JKU auth, toggle this to ON. |

</details>




<details>
<summary>OAuth 2.0 Two-Legged with secrets</summary>

When you select <u>**OAuth 2.0 Two-Legged with secrets**</u>, you must first select one of the following **grant types** for the relevant configuration fields to appear: 

- Client credentials
- Authorization code
- Resource owner password credentials
- Custom grant type

Fill out the necessary configuration details for this strategy type. Required fields are denoted with an asterisk in the dashboard. Basic fields are common configuration settings. For less common configuration options, click the **Show advanced** fields button. 

### Basic fields

| **Field** | **Notes** |
| --- | --- |
| Token endpoint URL | The authorization server URL, where the auth request is sent.  The authorization server typically provides this URL, so its structure varies.  If the token endpoint URL isn’t valid, it will result in a `4XX` error when trying to send a message to a destination using this auth credential. |
| Client ID | The OAuth client. The authorization server assigns this value. _Not available for_ <u>_custom grant type_</u>_._ |
| Client secret | The secret value assigned by the authorization server. _Not available for_ <u>_custom grant type_</u>_._ |
| Audience | The system that should consume the auth credentials. |
| Scope | The scope or access granted with the authentication credentials. |
| Refresh token grant type name | The method that’s used to grant a refresh token to and authenticate the OAuth client. |

<u>Resource owned password credentials</u> has these additional basic fields:

| **Field** | **Notes** |
| --- | --- |
| Username | Username for grant type, or basic authentication. |
| Password | Password for the grant type, or basic authentication. |

<u>Custom grant type</u> has this additional basic field: 

| **Field** | **Notes** |
| --- | --- |
| Custom grant type | A custom grant type option. If you define a custom value in the grant type field, then it should be defined here. |

### Advanced fields

| **Field** | **Notes** |
| --- | --- |
| Grant type parameter name | The property name for the `grant_type` field in the authorization request. The default value is `grant_type`. This field is an advanced option that should be used if the authorization server expects something other than `grant_type`. |
| Client ID parameter name | The property name for the `client_id` field in the authorization request. The default value is `client_id`. This field is an advanced option that should be used if the authorization server expects something other than `client_id`. |
| Client secret parameter name | The secret value assigned by the authorization server. |
| Refresh token parameter name | The name used to pass a refresh token when requesting a new access token (e.g., `refresh_token` or `refreshToken`). |
| Access token parameter name | The property name for the `access_token` field in the authorization response. The default value is `access_token`. This field is an advanced option that should be used if the authorization server responds with something other than `access_token`. |
| Expiration field name | The property name for the `expires_in` field in the authorization response. The default value is `expires_in`. This field is an advanced option that should be used if the authorization server responds with something other than `expires_in`. |
| Content type | The default type of payload for requests coming into your system with this auth credential. This value is located in the header of incoming API requests. The default value is `application/x-www-form-urlencoded`. |
| Suppress basic auth | Boolean option to determine whether to send the basic auth header. Some servers expect a basic auth header, including the client ID and secret, in the authorization request. The default behavior is to always send the basic auth header. Setting this field to `true` excludes the basic auth header from the request. |
| Resource URI | A specific resource that the OAuth client is requesting access to. This field isn’t required but is sent in the `resource` field of the authorization request when populated. |
| Custom field name | An additional field that the OAuth client can send in the authorization request, either in the header or body. To add a custom field to the header, it must start with `headers.`, otherwise it’ll appear in the body. |
| Custom field value | The value of the `customFieldName`, which is sent in the authorization request. |
| Default token expiration | The number of seconds that the access token is valid, if used. This field is only used if the authorization server doesn’t send an expiration value in the response. |
| No form data | Boolean option to determine whether the client ID and client secret should be included in the request form data. |

</details>




<details>
<summary>OAuth 2.0 2-legged with JWT for GCP</summary>

### GCP console

In the Google Cloud Platform (GCP) console:

1. Create a **service account**. [Learn how to create a GCP service account](https://docs.cloud.google.com/iam/docs/service-accounts-create).
2. Assign **permissions** to the account as needed for your workflow, depending on what you want to give Redox access to.
3. Create an **auth** **key** for your service account.
4. You’re prompted to download a JSON file containing your secret key details. **Save this file** since you’ll need to enter some of its details into the Redox dashboard. _This file contains secrets and shouldn't be shared via email or any other insecure method._
   - The three values you need from this file are:
     - **`private_key_id`**
     - **`private_key`**
     - **`client_email`**

### Redox dashboard

Fill out the necessary configuration details for this strategy type. Required fields are denoted with an asterisk in the dashboard.

Basic fields are common configuration settings. For less common configuration options, click the **Show advanced** fields button.

#### Basic fields

| **Field** | **Notes** |
| --- | --- |
| Token endpoint URL | Set this value to the **`token_uri`** field of the secret key file you downloaded from GCP. It represents the authorization server URL, where the auth request is sent. Typically, this value is `https://oauth2.googleapis.com/token`. However, it’s provided by the authorization server, so its structure may vary.  If the token endpoint URL isn’t valid, it will result in a `4XX` error. |
| Client ID | Set this value to the **`client_email`** from the secret key file you downloaded from GCP (e.g., `"clientId": "<client_email>"`). |
| Audience | The intended recipient of the access token. This is typically the URI of the resource server. This field is optional and can typically be left blank. |
| Scope | The scope or access granted with the authentication credentials. For example, set the scope to `https://www.googleapis.com/auth/devstorage.read_write` in order to give Redox read/write access to Google Cloud Storage (GCS). |
| JWT key ID | Set this value to the **`private_key_id`** from the secret key file you downloaded from GCP. This value is the identifier of the private/public key pair used to sign the JWT and is included in the JWT header as the `kid` property. |
| Private key | Set this value to the **`private_key`** from the secret key file you downloaded from GCP. Though this field isn’t required in the Redox dashboard, the auth credential requires this field to function appropriately.  _Note:_ The value in the downloaded file will be JSON-encoded (i.e., include `\n` characters instead of new lines). You must edit the private key to replace `\n` characters with line breaks before pasting into the Redox dashboard. If using an asymmetric signing algorithm such as `RS384`, this property contains the PEM-encoded private key that signs the JWT. |
| JWT algorithm | The JWT algorithm that’s supported to sign a private key. For GCP, this should be set to `RS256`.  All possible values: `HS256` `HS384` `HS512` `RS256` `RS384` `RS512` `PS256` `PS384` `PS512` `ES256` `ES384` `ES512` Though this field isn’t required in the Redox dashboard, the auth credential requires this field to function appropriately. |

#### Advanced fields

| **Field** | **Notes** |
| --- | --- |
| Custom grant type | The name of the custom grant type being used. This populates with the default value expected by GCP, but you can override the default, if needed. |

</details>




<details>
<summary>SMART backend</summary>

Fill out the necessary configuration details for this strategy type. Required fields are denoted with an asterisk in the dashboard.

Basic fields are common configuration settings. For less common configuration options, click the **Show advanced** fields button.

### Basic fields

| **Field** | **Notes** |
| --- | --- |
| Grant type | The method that’s used to grant access to and authenticate the OAuth client. Redox only supports `client_credentials`. |
| Token endpoint URL | The authorization server URL, where the authorization request is sent. |
| Client ID | The OAuth client. This value is assigned by the authorization server. |
| Scope | The scope or access granted with the authentication credentials. |
| Private key | An encrypted key that’s used to verify a system’s authenticity before it can access protected resources in another system. |
| JWT algorithm | The JWT algorithm that’s supported to sign a private key. The default value is `RS384`. Other possible values: `HS256` `HS384` `HS512` `RS256` `RS384` `RS512` `PS256` `PS384` `PS512` `ES256` `ES384` `ES512` |
| JWT key ID | The identifier of the private/public key pair used to sign the JWT. This identifier tells Redox which public key to use to verify the JWT. |

### Advanced fields

| **Field** | **Notes** |
| --- | --- |
| Client certificate | The X.509 certificate used for <u>**mutual TLS**</u> (<u>**mTLS**</u>) authentication when establishing the HTTPS connection to the token endpoint server. This is optional and separate from the JWT signing key. You only need this if the token endpoint requires mTLS. |
| Client certificate key | The private key associated with the <u>**client certificate**</u>. This is only required if a client certificate is provided for <u>**mTLS**</u> authentication. |
| Include x5t | A message header specific to JWT. Some systems require this header, in which case you can toggle this to ON. If not needed, toggle this to OFF. |
| Include JKU | JKU auth allows Redox to expose a URL that holds public keys for the auth credential. If you want to use JKU auth, toggle this to ON. |
| Custom field name | An additional field that the OAuth client can send in the authorization request, either in the header or body. To add a custom field to the header, it must start with `headers.`, otherwise it will appear in the body. |
| Custom field value | The value of the `customFieldName`, which is sent in the authorization request. |

</details>


8. When you’ve finished entering the configuration details, click the **Create** button. 
9. The form closes and the new auth credential appears on the <u>Authentication</u> tab.

## Edit an auth credential

1. Follow the steps to view auth credentials. 
2. Find the auth credential you want to edit and click anywhere in its **row**. 
3. The <u>Details</u> page opens. Click the **Edit** button. 
4. The form opens. Make any changes you need, then click the **Save** button. 
At any point, click the **Discard changes** button to undo any edits. 


![A user selects an auth credential to edit and updates its settings in the Redox dashboard.](https://images.ctfassets.net/cl3wt5ehhnlv/7oWMjui3ED31OcXVrJ05fD/356dbf3764d65f36e019e3d4bf9ff7e1/auth-credential-edit.gif)

*Edit an existing auth credential*



## Delete an auth credential

1. Follow the steps to view auth credentials. 
2. Find the auth credential you want to delete and click anywhere in its **row**.
3.  The <u>Details</u> page opens. Click the **Delete** button in the top-right corner.
4. A confirmation modal opens. Click the **Delete** button to proceed or click the **Cancel** button to keep it.  


![A user must confirm before an auth credential is successfully deleted.](https://images.ctfassets.net/cl3wt5ehhnlv/6CF2b7L3Ujw6aA8A5atF6w/70718cd18266c04e53b810a7b5f18da6/auth-credential-delete.gif)

*Delete an auth credential*



> **Platform API endpoints**
>
> This article describes how to manage auth credentials in the <u>**Redox dashboard**</u>. To manage auth credentials via <u>API</u>, use these <u>**Redox Platform API**</u> endpoints instead:
>
> - [Create auth credential](https://docs.redoxengine.com/permalink/dd0240f7-18d1-593d-87a7-d81bf86f543c-create-auth-cred)
> - [Update auth credential](https://docs.redoxengine.com/permalink/385d938b-6c43-5c43-b0fa-5b55fb09c036-patch-auth-cred)
> - [Delete auth credential](https://docs.redoxengine.com/permalink/a3c4893c-f741-5052-b1bd-4463a20aa2e3-delete-auth-cred)