Simple Notification Service (SNS)

Warning

This data source is deprecated and not available for use. This document remains viewable for legacy support and archival purposes.

If necessary, consider connecting to this service using a REST data source instead.

SNS is a push notification product that sends email and text messages based on its configuration. In conjunction with Skuid, this service can be used to send both custom messages—created by the end user at runtime—and automated messages to specific endpoints, perhaps notifying interested parties of updates to particular records.

For more general information, see Amazon’s Getting Started with Amazon Simple Notification Service.

Configuration

Creating an AWS authentication provider

Before configuring data sources within Skuid, you need to decide how you’ll authenticate to your AWS services using an IAM role. We recommend consulting your AWS administrator prior to making this decision.

Assume Role [[]]

This authentication method allows you to use the ARN of an assumable role instead of hard-coded AWS access keys. When a Skuid user makes a request using this authentication method, Skuid makes a secure server-side request to assume the configured role. If this request is successful, Skuid receives temporary access credentials, which Skuid caches until the credentials expire after 60 minutes.

Requests made through an assumed role are traceable via the AWS console. From there, you can see both the Skuid site and Skuid user who initiated the request, which provides AWS administrators full visibility into who requested access credentials and from what Skuid site.

Due to this method’s security and ease-of-management after initial setup, we typically recommend it over the access keys method. However, it does require some technical knowledge to configure. Be sure to read all of the instructions below.

Before you begin

Skuid can only access roles that have a defined path containing the string /skuid-assumable-role/ . This is different from the role’s name. Role paths can only be set when first created, so it isn’t possible to update an existing role with a new path.

In order to create a role with a path, you’ll need to use either the AWS IAM API or the AWS CLI.

The instructions below assume you are using AWS CLI (version 2) and that you’ve already configured an access key ID and secret access key for use with the CLI. Ensure these credentials have the iam:CreateRole permission. Command line examples are also tailored for Linux or macOS operating systems; commands for command line programs on Windows may differ.

Finally, because IAM roles require a trust relationship policy upon creation, you’ll need to save the JSON that Skuid provides when creating an authentication provider. Because of this you’ll need to navigate between your browser window, your computer’s file explorer, as well as the command line.

In Skuid

  1. From the Skuid navigation bar, navigate to Data Sources > Authentication Providers.
  2. Click Create.
  3. Configure the authentication provider’s basic properties:
    • Name: Enter a name, such as AWSAuth.
    • Authentication Method: AWS: Assume Role with ARN
  4. In the Trust Relationship Policy, click Copy to Clipboard.

This copied policy will enable your role to grant proper access to your Skuid site.

Note

If you want this role to be assumable by multiple Skuid sites—for example a staging site and a production site, make the sts:ExternalId property’s value into an array of Skuid site Ids.

For example, change this key/value:

"sts:ExternalId": "09583eba-de0e-49d3-ae42-61b3927a61b1"

Into this:

"sts:ExternalId": [
   "09583eba-de0e-49d3-ae42-61b3927a61b1",
   "e354e60f-5a80-4024-b01a-4cae13d0948c"
]

Site IDs are accessible from Settings > Site > Profile.

On your local machine

  1. With the policy copied to your clipboard, paste the policy into a text editor.
  2. Save the file to an easily accessible directory (for example, your desktop) on your machine with a recognizable name and the JSON file extension, like trust-policy.json

In a command line interface

With the trust policy saved to your machine, you can now use the AWS CLI to create an assumable role.

  1. Open your command line program of choice and navigate to the directory containing your policy JSON file. For example, if you saved the file on your desktop:

    1
    cd ~/Desktop
    
  2. Use the AWS CLI’s iam create-role command to create the role with the proper path value and trust relationship policy:

    1
    aws iam create-role --role-name Skuid-S3-Access --path /skuid-assumable-role/ --assume-role-policy-document file://trust-policy.json
    

    Note

    While role-name can vary from this example, the path must contain /skuid-assumable-role/

    The CLI creates the role, outputting its ARN and other related metadata. Because of the configured path, your ARN should look similar to this: arn:aws:iam::1234567891011:role/skuid-assumable-role/Skuid-S3-Access.

  3. Copy this created ARN, either from the command line output or the AWS console.

In Skuid

  1. Return to the authentication provider window.
  2. Paste the copied ARN into the AWS Role ARN to assume field.
  3. Click Save.

Access Keys [[]]

This authentication method utilizes an Amazon Web Service (AWS) IAM role’s access keys to authenticate to an AWS system.

If you are not the manager of your AWS services, follow along with Amazon’s steps for creating access keys with your IT administrator. You’ll need to do the following:

In AWS

  1. Create a new group and select the appropriate policies for that group.
    • These should align with your intended Skuid use. Ensure your access policies match the services (S3, DynamoDB, or SNS) you’ll be using.
  2. Create a new user in AWS Identity and Access Management (IAM) within the newly created group.
  3. Retrieve the access credentials generated for that user:
    • The secret access key is only displayed once, immediately after the access key is generated, and cannot be found later. Be sure to copy it to a safe place.

In Skuid

With your access credentials handy, you can now use them to configure a Skuid authentication provider that will work with all AWS data sources.

  1. Navigate to Configure > Data Sources > Authentication Providers.
  2. Click New Authentication Provider.
  3. Configure the authentication provider’s basic properties:
    • Name: Enter a name, such as AWSAuth.
    • Authentication Method: AWS: Access Keys
  4. Enter your IAM role’s credential information:
    • AWS Access Key Id: The access key ID to use when authenticating.
    • AWS Secret Access Key: The secret access key to use when authenticating.
  5. Click Save.

Adding AWS access permissions

After choosing an authentication method for your role, you must grant the role a certain set of IAM permissions to access AWS resources. Add each of these permissions to the role used to authenticate Skuid.

  • sns:CreateTopic
  • sns:DeleteTopic
  • sns:ListSubscriptions
  • sns:ListSubscriptionsByTopic
  • sns:ListTopics
  • sns:Publish
  • sns:Subscribe
  • sns:Unsubscribe

You can add these permissions using the AWS Console or the AWS CLI. You may use any managed policy that includes these permissions, or create a custom inline policy. For more information about these access options, refer to AWS documentation.

Note

When using AWS APIs, it is best practice to utilize strict and well-defined IAM policies so end users can only perform actions they have explicit access to.

Any examples within Skuid’s documentation assume the authenticated role has full access, but Skuid adheres to any policies associated with the AWS access credentials provided to it.

These permissions are important to consider in the broader context of your AWS implementation. Take care when assigning and unassigning permissions.

Creating an SNS data source

  1. Navigate to Data Sources > Data Sources.
  2. Click Create.
  3. Select Amazon SNS for Type.
  4. Enter an appropriate value for Name, such as AWS-ServiceName.
  5. Click Next.
  6. Select the previously configured AWS authentication provider.
  7. Select the AWS Region where the resources you need within Skuid reside. See AWS documentation on regions for more information.
  8. Click Save.

After creation, leave Use proxy disabled. The proxy does not currently support Amazon SNS data sources.

Using the AWS SNS data source

The SNS data source type contains only two entities, Topic and Subscription. Of the two, only Topic may be directly edited within Skuid components. Instead, this data source type’s potential lies within the interplay of its data source actions and Skuid components attached to these entities—which can then provide context.

Some basics:

  • Endpoint: A phone or email address that can receive a message from SNS.
  • Topics: A “message hub,” typically used for a specific subject matter or specific service. Messages are published to topics, which are then sent to all subscribed endpoints.
  • Subscription: The connection between an endpoint and a topic. A subscription ensures that messages published to a topic make their way to a specified endpoint.
  • ARNs (Amazon Resource Numbers). These are the unique identifiers of an Amazon resource.

Topic

The Topic entity returns a list of topics. New topics can be created within Skuid components, but data source actions must be used to publish messages to topics.

Fields

  • Name (default): The user-friendly name assigned to a topic.
  • Region: The geographical region in which the SNS topic resource is hosted.
  • Topic ARN: The unique identifier of the topic, which functions like a topic record ID. Used for several data source actions.

Subscription

The Subscription entity returns a list of subscriptions connected to a specified topic. It is read-only within Skuid components, but subscriptions can be added and deleted through the use of data source actions.

Fields

  • Endpoint: The email or phone number subscribed to the topic of the subscription.

  • Owner: This field relates to the owner of the topic of the subscription.

  • Protocol: Displays which protocol the subscription uses to deliver messages to an endpoint.

    For a list of SNS protocols, see AWS documentation.

  • Region: The geographical region in which the SNS subscription resource is hosted.

  • Subscription ARN: The unique identifier for this individual subscription, which functions like a subscription record ID.

  • Topic ARN: The unique identifier for the topic to which the endpoint is subscribed.

  • Topic Name: The user-friendly name assigned to the topic of the subscription.

Conditions

  • Topic (Required): Setting this condition’s value to a topic’s ARN will limit the model’s data to that topic’s subscriptions. If this condition is not set, this model will be unable to load data.

Data source actions

The power of the SNS data source type comes from its data source actions. While the Subscription model entity is read-only, these actions facilitate SNS subscription and message publishing.

  • Publish to Topic: Publishes a message to a topic, which SNS disperses to all endpoints subscribed to that topic.

  • Send Text to Number:

  • Subscribe to Topic: Used to subscribe an endpoint to an existing topic. Most likely to be used as a row action on a table for the Topic model entity.

    • Protocol: Set which protocol the subscription will use to deliver messages to an endpoint.

      For a list of SNS protocols, see AWS documentation.

    • Endpoint (phone/email): The phone number or email that will be subscribed to the topic. Accepts static strings as well as merge syntax.

    • Topic ARN: The ARN for the topic being subscribed to. Accepts static strings as well as merge syntax.

  • Unsubscribe from Topic:

    • Subscription ARN: The ARN for the topic being unsubscribed from. Accepts static strings as well as merge syntax.

Most of these actions require a topic ARN and a message. While these values can be set manually within the App Composer, they can also be passed in using merge syntax. Because of this, you’ll most often use these data source actions within:

  • Table Row actions: When applied as row actions on table for the Topic entity, the ARN fields can be passed in as context.

  • Button Sets and UI-only models: By attaching a Field Editor to a UI-only model, you provide end users with a form to enter the necessary information. By setting the Button Set component to that same model, buttons can be created for the actions that then receive the appropriate data.

    For example, end users can enter a message and a topic ARN in the Field Editor. They can then publish this message through a button in the Button Set.

Troubleshooting

When trying to select a model entity, I receive “An internal server error occurred” [[]]

The IAM user associated with your AWS access credentials within your Skuid authentication provider probably does not have the appropriate permissions for the service you are accessing. Return to the AWS console and ensure your IAM policy settings are correct.

If your policy settings are correct, recreate your authentication provider with a new access key.