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.

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.

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.

Mailgun

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

• API Key: The Mailgun API Key used to authenticate the request. This can be either an Account API Key or a Domain Sending Key. This value cannot be retrieved after creating or updating the credential.

MongoDB

A MongoDB credential can be used to authenticate connections to document databases through the MongoDB Node. It takes only one property:

• Connection URI: A connection string that contains the username, password, host, port, database name, and connection options. 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.

SQL

A SQL credential can be used to authenticate connections to MSSQL, MySQL, and PostgreSQL databases through the SQL Node. The credential takes the following properties:

• DBMS Type: The type of database this credential will connect to. Options are “MSSQL”, “MySQL”, or “PostgreSQL”. (SQLite 3 is not supported because the SQL Node only allows connecting to that database type in Edge Workflows, which do not support credentials.)
• SQL Server Address: The hostname used to connect to the credential’s database(s).
• Port: The port through which to connect to the SQL service on the host. This field is optional; if not provided, the port defaults to the default port for the selected database type.

• Secure Connection: Whether to establish a secure connection to the SQL server. This is enabled by default and is strongly recommended. If enabled, the following fields appear …

  • Disable SSL Verification: If checked, the SQL server’s SSL certificate will not be verified against known certificate authorities.
  • CA Certificate: Required to authenticate the request only if the SQL server uses a self-signed certificate or a certificate from a non-standard certificate authority. In most cases this can be left blank. (This input is disabled if “Disable SSL Verification” is checked.)
• Username: The username required for authenticating the request.
• Password: The password for the user establishing the connection. This value cannot be retrieved after creating or updating the credential.

SQL Considerations

While most SQL services use a one-to-one relationship between users and databases - as in, every user has access to only a single database - it is possible to allow one user to access multiple databases managed by the service. To that end - and because it is not considered protected - the database name is not included as part of the credential. When utilizing a SQL credential in a SQL Node, you must continue providing the database name in the node configuration.

Also, if attempting to update the DBMS Type, SQL Server Address, Port, or Secure Connection flag after creating the credential, you must also provide the Password again. This is to prevent the leaking of sensitive information to malicious actors, who could potentially steer SQL requests to a server under their control to retrieve the user’s password.

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 several services provided through a Losant application.

Integrations

Losant’s real-time, bi-directional integrations to Amazon SQS, Azure Event Hubs, and Google Pub/Sub - as well as WebSocket integrations - 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 in several workflow nodes as a means for …

• Authenticating connections to 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.
• Passing API authorization information through HTTP headers, query parameters, basic authentication, or client certificates using the HTTP Node.
• Connecting with databases using the MongoDB Node or SQL Node.
• Interacting with third-party services, such as the MailGun Node, WhatsApp Node, and others.
• Signing and verifying tokens using the JWT: Create and JWT: Verify Nodes.

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.

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.