Chapter 32. Extensions

32.1. Email Service

The automatic configuration of the email service supports handler, protocol, request and response messages.

The email service is a ServiceBlox service which accepts a JSON or protobuf request defined by the following protocol:

message SendEmailRequest
{
  required string from = 1;
  repeated string reply_to = 2;

  repeated string to = 3;
  repeated string cc = 4;
  repeated string bcc = 5;

  required string subject = 6;
  required string body = 7;
}

32.1.1. Service configuration via SMTP and SES

The email service can be configured either using SMTP or Amazon Simple Email Service (SES).

Configuring an email services using SES is very easy, as the example below illustrates. The SES configuration uses the AWS SES API directly, it is therefore possible to use IAM (Amazon's Identity and Access Management) roles for authentication.

block(`service_config) {

  alias_all(`lb:web:config:service),
  alias_all(`lb:web:config:service_abbr),

  alias_all(`lb:web:email:service_config),

  clauses(`{

    /**
     * Email service only hosted on internal group. This can
     * only be used with manual testing, because AWS credentials are
     * needed.
     */
    service_by_group["/admin/email", "lb:web:internal"] = x,
    ses_email_service(x).
  })

} <- .

The example below illustrates how to configure an email service via SMTP, by setting the configuration parameters directly in the service.

block(`service_config) {

  alias_all(`lb:web:config:service),
  alias_all(`lb:web:config:service_abbr),

  alias_all(`lb:web:email:service_config),

  clauses(`{

    service_by_group["/admin/email", "lb:web:internal"] = x,
    smtp_email_service(x) {
        service_parameter["smtp_server"]="smtp.gmail.com",
        service_parameter["smtp_server_port"]="587",
        service_parameter["smtp_server_user"]="...",
        service_parameter["smtp_server_pwd"]="....",
        service_parameter["smtp_server_auth"]="true",
        service_parameter["smtp_server_tls"]="true"
        }.

  })

} <- .

Tip

You will have to include the lb_web_email library in your project.

The two tables below list the configuration parameters for using SMTP as well as SES. All the properties listed below can be configured either on the service, in the lb-web-server.config handler section, or in the global ServiceBlox section.

Email service using SMTP
Required parameters
smtp_server

Hostname of the SMTP server.

smtp_server_port

Port of the SMTP server.

smtp_server_user

User account for sending email.

smtp_server_pwd

User password for sending email.

Email service using SMTP
Optional parameters
smtp_server_auth

Use authentication or not (true or false).

smtp_server_ssl

Use SSL SMTPS protocol (true or false).

smtp_server_tls

Use TLS protocol (true or false).

debug

Prints detailed information to the log while communicating with the mail server. This can be useful if you experience problems in sending emails.

Email service using SES
Optional authentication parameters
access_key

AWS access key.

secret_key

AWS secret key.

iam_role

Use IAM EC2 instance role (set to any value).

env_credentials

Use environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_KEY.

By default environment credentials are tried first, followed by IAM roles.

Example configuration using Gmail:

smtp_server = smtp.gmail.com
smtp_server_port = 587
smtp_server_user = ...
smtp_server_pwd = ...
smtp_server_auth = true
smtp_server_tls = true

32.2. Password Management

ServiceBlox comes with services for changing and resetting passwords. The automatic configuration of these services supports handler, protocol, request and response messages. Other service configuration aspects (such as the service group or authentication realm) can be figured by the developer on the service.

32.2.1. Change Password

In order to change the password of a user, the client must send a request to the change password service of ServiceBlox. The change password service is a ServiceBlox service which accepts a JSON or protobuf request defined by the following protocol:

message ChangePasswordRequest
{
  required string user_name = 1;
  required string current_password = 2;
  required string new_password = 3;
}

Service Configuration

A change password service is configured with ServiceBlox by creating a change_password_service. Example:

block(`service_config) {
  alias_all(`lb:web:config:service),
  alias_all(`lb:web:config:service_abbr),

  alias_all(`lb:web:credentials:password_management),

  clauses(`{

    /**
     * Change a password
     */
    service_by_prefix["/user/change-password"] = x,
    change_password_service(x).
  })

} <- .

Service Parameters

A change password service supports the following optional service_parameter:

credentials_url

URL of credentials service (default: http://localhost:55183/admin/credentials)

This property can be configured either on the service, in the lb-web-server.config handler section, or in the global ServiceBlox section.

32.2.2. Reset Password

ServiceBlox also comes with services to reset passwords. Application developers should develop a user interface supporting the following process flow:

  1. The reset password service is not authenticated. A user can invoke the reset password service with his username or email address.

  2. The reset password request generates a token that is stored in the database as a reset password request for the given user.

  3. A configurable email is sent using the email service to the user.

  4. The user can click on a link in the email, which brings him to a client-side page where the user can enter the token in the UI.

  5. Optional: once the password has been changed, a confirmation email is sent to the user.

In order to reset the password of a user, the client must send a request to the reset password service of ServiceBlox. The reset password service is a ServiceBlox service which accepts a JSON or protobuf request defined by the following protocol:

message ResetPasswordRequest
{
  optional string user_name = 1;
  optional string email = 2;
}

Tip

Passwords can be reset either by email or username. If the username is specified, then the email address is ignored.

The protocol to confirm the reset of a password is defined as:

message ConfirmResetPasswordRequest
{
  required string change_token = 1;
  required string new_password = 2;
}

Service Configuration

A reset password service is configured with ServiceBlox by creating a reset_password_service. In the example below an email is sent from to the user, containing the user name, the token and the date/time until the token is valid. Additionally, the service_parameter "notify" is set to false, which means that no confirmation email is sent to the user, once the email is reset. An SES email service is used for sending the email regarding the reset of the forgotten password.

block(`service_config) {
  alias_all(`lb:web:config:service),
  alias_all(`lb:web:config:service_abbr),

  alias_all(`lb:web:credentials:password_management),
  alias_all(`lb:web:email:service_config),

  clauses(`{

    /**
     * Reset a forgotten password
     */
    service_by_prefix["/user/reset-password"] = x,
    reset_password_service(x) {
      service_parameter["email_template"] =
        "User: {USER}\nToken: {TOKEN}\nValid until: {VALID}\nTime: {TIME}",
      service_parameter["email_from"] = "support@logicblox.com"
    }.

    /**
     * Do not confirm the reset of a forgotten password
     */
    service_by_prefix["/user/confirm-reset-password"] = x,
    confirm_reset_password_service(x) {
      service_parameter["notify"] = false
    }.

    /**
     * Email service only hosted on internal group. This can
     * only be used with manual testing, because AWS credentials are
     * needed.
     */
    service_by_group["/admin/email", "lb:web:internal"] = x,
    ses_email_service(x).
  })

} <- .

Service Parameters

All of the properties listed in this section can be configured either on the service, in the lb-web-server.config handler section, or in the global ServiceBlox section.

A reset password service supports the following service_parameter:

Required service_parameter
email_template

The template for the email. Supports {USER}, {TOKEN}, {IP}, {VALID} and {TIME}.

email_from

The address where emails are sent from.

Optional service_parameter
Parameter Description Default
credentials_url The URL of the credentials service http://localhost:55183/admin/credentials
valid_hours The number of hours a reset token is valid. 4 hours
email_url The URL of the email service. http://localhost:55183/admin/email
email_subject Subject of the reset password email. Password reset

A confirm reset password service supports the following service_parameter:

Required service_parameter
email_template

The template for the email. Supports {USER}, {TOKEN}, {IP}, {VALID} and {TIME}.

email_from

The address where emails are sent from.

Optional service_parameter
Parameter Description Default
credentials_url

The URL of the credentials service.

http://localhost:55183/admin/credentials

notify

Setting whether user should be emailed when the password is changed.

true
email_url

The URL of the email service.

http://localhost:55183/admin/email
email_subject

Subject of the reset password email.

Password change notification

32.3. ConnectBlox Services

The ConnectBlox extension exposes some of the more low level functionality of LogicBlox through typical protobuf web services. These services map very closely to functionality found in the lb command line tool but are accessible over the web and are secured in the same way as other ServiceBlox services.

32.3.1. Configuring Services

The ConnectBlox services are subtypes of the default_protobuf_service entity. They each have their own custom_handler and protobuf request and response message (which are documented in the following service specific sections). The schemata for these services are in the lb:web:connectblox:services module. A snippet follows.

connectblox_service(x) -> default_protobuf_service(x).
// defaults to the workspace hosting the service
// You can use regular expressions to match multiple workspaces.
connectblox_service_workspaces[x] = ws -> connectblox_service(x), string(ws).

list_workspaces_service(x) -> default_protobuf_service(x).

pred_info_service(x) -> connectblox_service(x).
list_predicates_service(x) -> connectblox_service(x).
exec_service(x) -> connectblox_service(x).

Examples of configuring these services can be found in the ServiceBlox repository under lb-web-samples/lb-web-connectblox. An example of configuring the list-predicates service follows.

service_by_prefix["/list-predicates"] = x,
list_predicates_service(x) {
  auth_realm[] = "list-predicates-realm"
}.

Another feature of these services is the ability to specify which workspace you wish to run against. For example, if your services are hosted in a workspace called services and you want to list predicates in a workspace called staging, you can do so by configuring the service to allow access to the staging workspace. You do that by specifying a regular expression that matches the workspaces to which that service has access. For the previous example, you could do either of the following:

service_by_prefix["/list-predicates"] = x,
list_predicates_service(x) {
  auth_realm[] = "list-predicates-realm",
  connectblox_service_workspaces[] = "services|staging" // only matches services or staging
}.

service_by_prefix["/list-predicates"] = x,
list_predicates_service(x) {
  auth_realm[] = "list-predicates-realm",
  connectblox_service_workspaces[] = ".*" // matches any workspace name
}.

If you do not specify any value for the connectblox_service_workspaces predicate, that indicates that the service will only have access to the workspace in which the service is hosted.

32.3.2. Services Protobuf Schema

import "blox/connect/ConnectBlox.proto";
import "blox/connect/BloxCommand.proto";
import "blox/common/Common.proto";
package web.connectblox;

option java_package = "com.logicblox.web.connectblox";

message ExecRequest {
  required blox.connect.ExecBlock execute = 1;
  optional string workspace_name = 2;
}

message ExecResponse {
  required blox.connect.ExecBlockResponse response = 1;
  optional Error error = 10;
}

message ListWorkspacesRequest
{
}

message ListWorkspacesResponse
{
  optional blox.connect.ListWorkSpacesResponse workspaces = 1;
  optional Error error = 10;
}

message PredicateInfoRequest
{
  required string qualified_name = 1;
  optional string workspace_name = 2;
}

message PredicateInfoResponse
{
  optional blox.common.protocol.PredicateInfo info = 1;
  optional Error error = 2;
}

message ListPredicatesRequest
{
  repeated string qualified_name = 1; // if empty return all predicates
  optional string workspace_name = 2;
}

message ListPredicatesResponse
{
  repeated blox.common.protocol.PredicateInfo info = 1;
  optional Error error = 2;
}

message Error {
  // English error, not necessarily suitable for presentation to the
  // user. If there was an error, then the error_code field is always
  // set as well.
  optional string error = 1; // change this to 'message'
  optional string error_code = 2;
}

32.3.3. Services Reference

Service Request message Response message Description
web:connectblox:services:list_workspaces_service ListWorkspacesRequest ListWorkspacesResponse

Lists all available workspaces.

web:connectblox:services:pred_info_service PredicateInfoRequest PredicateInfoResponse

Returns predicate information about a predicate.

web:connectblox:services:list_predicates_service ListPredicatesRequest ListPredicatesResponse

Returns predicate information about some or all predicates in a workspace.

web:connectblox:services:exec_service ExecRequest ExecResponse

Executes a snippet of logic against a workspace.