Set up auth credentials

An auth credential verifies one of your destinations to receive data from Redox. Learn about receiving data from Redox.

• Any user can view auth credentials in a given environment, but a user must be assigned to an engineer role to manage them. Learn about user roles.
• You must have completed onboarding to Redox and implemented at least one connection.
• Use Network Explorer 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 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

1. Log in to the Redox dashboard.
2. From the navigation menu, click the Developer page.
3. By default, the Sources 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.

1. Log in to the dashboard.
2. From the navigation menu, select the Developer page.
3. By default, the Sources 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 New auth credential form opens. Enter a human-readable name for the auth credential. This will appear in the Authentication table. At any point, click the Cancel button to discard and exit the form.
6. From the Strategy drop-down field, select the relevant auth strategy that the auth credential will use to verify the source’s legitimacy.

   
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.

   AWS Signature Version 4

   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 Healthlake or S3. 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 Product type, 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.

   Google Workload Identity Federation (WIF)

   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.

   JWT bearer

   When you select JWT Bearer, 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.

   OAuth 2.0 Two-Legged with secrets

   When you select OAuth 2.0 Two-Legged with secrets, 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 custom grant type.
   Client secret	The secret value assigned by the authorization server. Not available for custom grant type.
   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.

   Resource owned password credentials has these additional basic fields:

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

   Custom grant type 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.

   OAuth 2.0 2-legged with JWT for GCP

   GCP console

   In the Google Cloud Platform (GCP) console:

   1. Create a service account. Learn how to create a GCP service account.
   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.

   SMART backend

   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 mutual TLS (mTLS) 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 client certificate. This is only required if a client certificate is provided for mTLS 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.

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 Authentication tab.

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

   

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