Create an auth credential

Last updated: Dec 10, 2024

IMPLEMENTATION

HEALTH TECH VENDOR

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

Platform API endpoints

This article contains instructions for managing auth credentials in the Redox dashboard. If you'd like to create and manage auth credentials via API instead, use these Platform API endpoints:

Only for engineer roles

Any user in a given environment may view connectivity settings, including sources, destinations, API keys, and authentication credentials. However, you must be assigned to an engineer role to manage them (i.e., create, verify, edit, or delete). Learn about roles.

This how-to is only for users with an engineer role.

Create an auth credential

Log in to the Redox dashboard.
From the navigation menu, click the Developer page.
By default, the API Keys tab displays. From the tab options, click the Endpoints tab.
Any configured destinations display. Click the Create auth credential button.
The auth credential wizard opens. Enter a human-readable name for the auth credential. This will be the displayed name on the Endpoints tab.
From the Strategy drop-down field, select the relevant auth strategy that the auth credential will use to verify the source's legitimacy.
Click the Next button.
More configuration fields display. These are specific to the selected auth strategy type. See the relevant section below these steps for more details.
When you've finished entering the configuration details, click the Create button. At any point, you can click the Cancel button to clear and reset the form.
Tip for masked secret values
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.
Pro tip: We recommend first pasting a value for masked fields into a text editor between quotes to check for extra whitespace.

AWS Signature Version 4

Field	Notes
Access key	The AWS access key ID provisioned for API calls to the AWS service.
Secret key	The AWS secret key ID provisioned for API calls to the AWS service.
Service name	The AWS service name to connect to (e.g., healthlake). If you're creating a new auth credential within the destination wizard, this field automatically populates based on the cloud product you selected (e.g., healthlake or s3).
AWS region	The AWS region the service is in (e.g., us-east-1). If you're creating a new auth credential in the dashboard, this field automatically populates based on the cloud product you selected (e.g., healthlake or s3).

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

Google Workload Identity Federation (WIF)

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

From the Strategy drop-down field, select JWT Bearer.
The JWT algorithm drop-down field appears with the following options. This describes which JWT algorithm is supported to sign a private key. The default value is RS384. The group of configuration fields change depending on your selection.
- HS256
- HS384
- HS512
- RS256
- RS384
- RS512
- PS256
- PS384
- PS512
- ES256
- ES384
- ES512
Fill out the necessary configuration details for this 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>").
Token endpoint URL	The authorization server URL, where the authorization request is sent.

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

From the Strategy drop-down field, select OAuth 2.0 Two-Legged with secrets.
The Grant type drop-down field appears with the following options. The group of configuration fields change depending on your selection.
- 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 authorization request is sent.
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

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

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.

Field	Notes
Client certificate	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 certificate key	The private key associated with the client certificate.
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.

Edit an auth credential

Log in to the Redox dashboard.
From the navigation menu, click the Developer page.
By default, the API Keys tab displays. From the tab options, click the Endpoints tab.
Any configured destinations display. Find the auth credential you want to edit, then click the Edit button.
The edit form opens. Make any changes you need, then click the Save button.

Delete an auth credential

Log in to the Redox dashboard.
From the navigation menu, click the Developer page.
By default, the API Keys tab displays. From the tab options, click the Endpoints tab.
Any configured destinations display. Find the auth credential you want to delete, then click the Delete button.
A warning dialog opens. If you changed your mind and want to keep the auth credential, click the Cancel button. Or to proceed with deleting, click the Delete button.
The page reloads with any remaining auth credentials.

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.