Service Credentials

Service Credentials are a method of securely storing authentication keys for third-party services that are accessed through integrations, workflow nodes, and application archiving.

Viewing Service Credentials

View your application’s Service Credentials under the “Service Credentials” link in the application’s navigation. This displays a list of all of your application’s Service Credentials, including each credential’s type.

Click a credential from the list to view its configuration, make edits, or view its usage across your application.

Creating Service Credentials

From the Service Credentials list page, click “Add Service Credential” in the top right corner. On the next screen, choose which type of credential to create, with the type corresponding to the cloud service provider or third-party API whose services you are connecting with your application. The type cannot be changed after the credential is created.

Service Credential Settings

Once you have selected a credential type, fill out the following fields on the next screen:

• Name: The name of the Service Credential. This field is required, and it must be unique within your application.
• Enabled: A checkbox indicating if the credential is enabled. Unchecking this box will retain the credential within your application, but any attempted uses of it will fail. New credentials are enabled by default.
• Description: Allows for a longer description of the credential and its intended use. This field is optional.

Each credential type requires additional fields that must be filled out.

Amazon Web Services (AWS)

An Amazon Web Services credential requires the following information, which can be found in the IAM console:

• AWS Region: The AWS region where the services the credential is accessing are hosted.
• Access Key ID: The ID associated with the IAM access key.
• Access Key Secret: The secret portion of the access key. This value cannot be retrieved after creating or updating the credential.

Microsoft Azure

A Microsoft Azure credential takes the following information, which can be found in the Azure service’s interface:

• Account Name: The name of the account associated with the token. This field is optional; however, most Azure services require this value so it should be provided for the majority of use cases.
• Account Key: The token used to authenticate the request. This value cannot be retrieved after creating or updating the credential.

Google Cloud Platform (GCP)

A Google Cloud Platform credential takes a Service Account Key, which is a JSON object containing several properties. When updating this value in the future, the entire account key object must be included in the request.

The object’s private_key property is redacted after creation and updates and cannot be retrieved.

HTTP

An HTTP credential can be used to authenticate WebSocket integrations and requests made through the HTTP Node. It takes the following information:

• Credential URI: The URI that the credential will be allowed to make requests to. Sub-paths and query parameters may be provided in the HTTP Node configuration. If updating this value after creating the credential, you must also provide the authentication info as part of the request to prevent unauthorized access to the credential.

• Authentication Method: The method for authenticating the node’s request; the method you choose depends on what is accepted by the service you are making the request to …

  • HTTP header: Appends the provided header name and value to the request. The header value can be updated but not retrieved after creating the credential.
  • Query parameter: Appends the provided query parameter name and value to the request. The query parameter value can be updated but not retrieved after creating the credential.
  • Basic (username and password): Attaches the provided username (optional) and password to the request through the Authorization header. The password can be updated but not retrieved after creating the credential.
  • Client certificate: Adds the provided client certificate and client certificate key to the request. The client certificate key can be updated but not retrieved after creating the credential.

Note: Credentials using the http and https protocols may only be used in the HTTP Node, and credentials using the ws and wss protocols may only be used to authenticate WebSocket integrations.

JSON Web Tokens (JWT)

A JWT credential can be used to securely sign and verify tokens using the JWT: Create Node and the JWT: Verify Node. It takes the following properties:

• Issuer: (optional) The “iss” (issuer) claim identifies the principle that issued the JWT. This value is most commonly your company’s domain (e.g. example.com).
• Algorithm: The algorithm used to generate the JWT signature. This is most commonly HS256.
• Secret: The secret value that’s incorporated into the JWT signature. This value should be similar to a strong password and should never be shared. This value cannot be retrieved after creating or updating the credential.

Loggly

A Loggly credential can be used to authenticate requests to send application logs through the Loggly: Write Node. It takes only one property, which can be found in your Loggly account’s interface:

• Customer Token: The Loggly customer token used to authenticate the request to write logs. (This is not to be confused with a Loggly API token, which can only read logs.) This value cannot be retrieved after creating or updating the credential.

SendGrid

A SendGrid credential can be used to authenticate requests to send emails through the SendGrid Node. It takes only one property, which can be found in your SendGrid account’s interface:

• API Key: The SendGrid API Key used to authenticate the request. This value cannot be retrieved after creating or updating the credential.

Twilio

A Twilio credential can be used to authenticate requests to send text messages (SMS) through the Twilio Node. It takes the following properties, which can be found in your Twilio account’s interface:

• Account SID: The unique ID associated with your Twilio account. This value always starts with “AC”.
• API Key SID: The SID of the API key to authenticate with. This value always starts with “SK”.
• API Key Secret: The secret value associated with the provided API Key SID. This value cannot be retrieved after creating or updating the credential.

WhatsApp

A WhatsApp credential can be used to authenticate requests to send messages through the WhatsApp Node. It takes the following properties, which can be found in your WhatsApp account’s interface:

• From Number ID: The ID of the From Number that this credential has permissions to send messages from.
• Access Token: An access token for yor WhatsApp Business account. This value cannot be retrieved after creating or updating the credential.

Using Service Credentials

Service Credentials can be used to authenticate against any of the major cloud provider services that have first-class support in the Losant platform, as well as third-party APIs that can be accessed through the HTTP Node.

Integrations

Losant’s real-time, bi-directional integrations to Amazon SQS, Azure Event Hubs, and Google Pub/Sub can all use Service Credentials to authenticate their connections to those services. In some cases, utilizing a credential may require additional settings in the integration configuration.

Note: When updating a Service Credential, any integrations that reference the credential for authentication will automatically reconnect to ensure that they are utilizing the new settings. In the case of invalid connection info – or if the new credential lacks permissions from the cloud vendor to utilize the service - the integration will fail to reconnect.

Workflow Nodes

Service Credentials can be used as an authentication method in any workflow node that connects with a cloud provider’s managed service, such as the AWS: Lambda Node, the Azure: Table Storage Node, or the GCP: BigQuery Node, amongst several others. Third-party APIs that accept authorization through HTTP headers, query parameters, basic authentication, or client certificates can also use Service Credentials to authenticate requests made using the HTTP Node.

Credentials can be selected directly from your application, or they may be referenced by name using a string template.

Service Credentials cannot be used in Edge Workflows; they are only a valid configuration option for nodes used in Application Workflows, Experience Workflows, and Custom Nodes built for those two flow classes.

Data Archiving

Daily application archiving also supports Service Credentials as an authentication method for writing data backups to Amazon S3, Azure Blob Storage, and Google Cloud Storage. When using a credential to authenticate, you must still provide the bucket/container name for where to place the daily archive files, and the credential must have permission to write to that bucket.

Viewing Usage

From a Service Credential’s detail screen, click the “Usage” tab to view any workflows, custom nodes, integrations, or archive configuration where the credential is being used. This helps to track down any application configuration that may need to change if you are editing or deleting the credential.

In the case of workflows and custom nodes, an item will appear in the table if any version of the resource references the credential.

Editing Service Credentials

To change the authentication values for a given credential, click the “Make Changes” link within the “Credential Configuration” panel to unlock the populated and redacted inputs. You may then update the values with the new settings from the cloud provider. If the link was clicked in error, you may click “Revert Changes” to discard any updates and return the form to its original state.

Once you are finished, click “Save Service Credential” to commit the updates; any requests to use the credential after this point will reference the new values.

Changing a Credential’s Name

Changing a credential’s name will cause all uses of it to fail. This is because credentials are referenced by name – not by ID – wherever they are used. For this reason, the “Name” field is locked in the user interface to prevent accidental updates; users must click the “Edit” link in the input’s label to unlock it before making any changes.

If you must change a credential’s name, you should first change any usage of the credential to reference the new name before changing the name of the credential.

Security Considerations

To protect the integrity of a Service Credential, there are a handful of limitations imposed on their use that developers should keep in mind …

Irretrievable Properties

Each credential type has properties that may be set on creation and update, but never retrieved. This is the primary security benefit of using Service Credentials within your application, as this greatly reduces the risk of provider-issued authentication values being leaked to unauthorized users.

When retrieving a credential, information that is not considered sensitive (such as the Access Key ID in AWS, the Account Name in Azure, the Project ID in Google, or the header name or query parameter name in HTTP requests) is still visible; this helps correlate a Losant Service Credential to an authorization resource in the cloud provider’s interface.

Edge Workflows

As noted above, Service Credentials cannot be utilized in Edge Workflows. This is because the sensitive authentication values would have to be transmitted to the Edge Compute Device for use, and even if they were encrypted at rest, the decryption keys would also be stored on the device – leaving the values retrievable to anybody who gained physical access to the hardware.

Application Exports

Service Credentials are never included in application export bundles. Doing so would expose the credential’s sensitive information in a plain text file that could fall into unauthorized hands. For this reason, any export bundle referencing a credential that is then imported as a new application or into an existing application requires creating a credential of the same name and type within the receiving application. Failing to do so will cause any uses of the credential in the receiving application to fail.

Application Clones

Similarly, Service Credentials are never included in application clones. While the credential’s sensitive information would not be at risk, cloning an organization’s application to a different organization or to a sandbox could allow untracked, unauthorized access to a company’s corporate cloud infrastructure. Therefore, cloned applications also require recreating credentials of the same name and type.

HTTP Restrictions

HTTP Service Credentials may only be utilized for the URI specified as part of the credential configuration, or for any sub-path of that URI. This is to prevent malicious users from making a credential-authenticated request to a server under their control, which would allow the user to view the HTTP headers, query parameters, and sensitive authentication information associated with the credential.

To that end, any updates to an HTTP Service Credential that modify the URI property must also include a new secret value (the HTTP header value, query parameter value, password for basic authentication, or client certificate key) to prevent malicious actors from changing the credential to a domain they control.

Finally, any headers or query parameters that are included in a credential-authenticated request will have their values redacted from the HTTP Node’s request object in any workflow debug output; this prevents their retrieval from the workflow’s debug log.

Deleting Service Credentials

To delete a Service Credential, click the “Delete” icon next to any item on the list page, or by clicking the “Delete” button in the footer of a credential’s edit page. Doing so will immediately remove the credential from your application, and any attempted uses of the credential within your integrations, workflows, or application archiving will fail.

You may, however, create a new credential of the same name and type, and any uses of the previous credential will automatically use the connection settings provided in the new credential.