clients

README

Clients

Clients service provides an HTTP API for managing platform resources: clients and channels. Through this API clients are able to do the following actions:

• provision new clients
• create new channels
• "connect" clients into the channels

For an in-depth explanation of the aforementioned scenarios, as well as thorough understanding of SuperMQ, please check out the official documentation.

Configuration

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

Variable	Description	Default
SMQ_CLIENTS_LOG_LEVEL	Log level for Clients (debug, info, warn, error)	info
SMQ_CLIENTS_HTTP_HOST	Clients service HTTP host	localhost
SMQ_CLIENTS_HTTP_PORT	Clients service HTTP port	9000
SMQ_CLIENTS_SERVER_CERT	Path to the PEM encoded server certificate file	""
SMQ_CLIENTS_SERVER_KEY	Path to the PEM encoded server key file	""
SMQ_CLIENTS_AUTH_GRPC_HOST	Clients service gRPC host	localhost
SMQ_CLIENTS_AUTH_GRPC_PORT	Clients service gRPC port	7000
SMQ_CLIENTS_AUTH_GRPC_SERVER_CERT	Path to the PEM encoded server certificate file	""
SMQ_CLIENTS_AUTH_GRPC_SERVER_KEY	Path to the PEM encoded server key file	""
SMQ_CLIENTS_DB_HOST	Database host address	localhost
SMQ_CLIENTS_DB_PORT	Database host port	5432
SMQ_CLIENTS_DB_USER	Database user	supermq
SMQ_CLIENTS_DB_PASS	Database password	supermq
SMQ_CLIENTS_DB_NAME	Name of the database used by the service	clients
SMQ_CLIENTS_DB_SSL_MODE	Database connection SSL mode (disable, require, verify-ca, verify-full)	disable
SMQ_CLIENTS_DB_SSL_CERT	Path to the PEM encoded certificate file	""
SMQ_CLIENTS_DB_SSL_KEY	Path to the PEM encoded key file	""
SMQ_CLIENTS_DB_SSL_ROOT_CERT	Path to the PEM encoded root certificate file	""
SMQ_CLIENTS_CACHE_URL	Cache database URL	redis://localhost:6379/0
SMQ_CLIENTS_CACHE_KEY_DURATION	Cache key duration in seconds	3600
SMQ_CLIENTS_ES_URL	Event store URL	localhost:6379
SMQ_CLIENTS_ES_PASS	Event store password	""
SMQ_CLIENTS_ES_DB	Event store instance name	0
SMQ_CLIENTS_STANDALONE_ID	User ID for standalone mode (no gRPC communication with Auth)	""
SMQ_CLIENTS_STANDALONE_TOKEN	User token for standalone mode that should be passed in auth header	""
SMQ_JAEGER_URL	Jaeger server URL	http://jaeger:4318/v1/traces
SMQ_AUTH_GRPC_URL	Auth service gRPC URL	localhost:7001
SMQ_AUTH_GRPC_TIMEOUT	Auth service gRPC request timeout in seconds	1s
SMQ_AUTH_GRPC_CLIENT_TLS	Enable TLS for gRPC client	false
SMQ_AUTH_GRPC_CA_CERT	Path to the CA certificate file	""
SMQ_SEND_TELEMETRY	Send telemetry to supermq call home server.	true
Clients_INSTANCE_ID	Clients instance ID	""

Note that if you want clients service to have only one user locally, you should use CLIENTS_STANDALONE env vars. By specifying these, you don't need auth service in your deployment for users' authorization.

Deployment

The service itself is distributed as Docker container. Check the clients service section in docker-compose file to see how service is deployed.

To start the service outside of the container, execute the following shell script:

# download the latest version of the service
git clone https://github.com/absmach/supermq

cd supermq

# compile the clients
make clients

# copy binary to bin
make install

# set the environment variables and run the service
Clients_LOG_LEVEL=[Clients log level] \
Clients_STANDALONE_ID=[User ID for standalone mode (no gRPC communication with auth)] \
Clients_STANDALONE_TOKEN=[User token for standalone mode that should be passed in auth header] \
Clients_CACHE_KEY_DURATION=[Cache key duration in seconds] \
Clients_HTTP_HOST=[Clients service HTTP host] \
Clients_HTTP_PORT=[Clients service HTTP port] \
Clients_HTTP_SERVER_CERT=[Path to server certificate in pem format] \
Clients_HTTP_SERVER_KEY=[Path to server key in pem format] \
Clients_AUTH_GRPC_HOST=[Clients service gRPC host] \
Clients_AUTH_GRPC_PORT=[Clients service gRPC port] \
Clients_AUTH_GRPC_SERVER_CERT=[Path to server certificate in pem format] \
Clients_AUTH_GRPC_SERVER_KEY=[Path to server key in pem format] \
Clients_DB_HOST=[Database host address] \
Clients_DB_PORT=[Database host port] \
Clients_DB_USER=[Database user] \
Clients_DB_PASS=[Database password] \
Clients_DB_NAME=[Name of the database used by the service] \
Clients_DB_SSL_MODE=[SSL mode to connect to the database with] \
Clients_DB_SSL_CERT=[Path to the PEM encoded certificate file] \
Clients_DB_SSL_KEY=[Path to the PEM encoded key file] \
Clients_DB_SSL_ROOT_CERT=[Path to the PEM encoded root certificate file] \
Clients_CACHE_URL=[Cache database URL] \
Clients_ES_URL=[Event store URL] \
Clients_ES_PASS=[Event store password] \
Clients_ES_DB=[Event store instance name] \
SMQ_AUTH_GRPC_URL=[Auth service gRPC URL] \
SMQ_AUTH_GRPC_TIMEOUT=[Auth service gRPC request timeout in seconds] \
SMQ_AUTH_GRPC_CLIENT_TLS=[Enable TLS for gRPC client] \
SMQ_AUTH_GRPC_CA_CERT=[Path to trusted CA certificate file] \
SMQ_JAEGER_URL=[Jaeger server URL] \
SMQ_SEND_TELEMETRY=[Send telemetry to supermq call home server] \
Clients_INSTANCE_ID=[Clients instance ID] \
$GOBIN/supermq-clients

Setting Clients_CA_CERTS expects a file in PEM format of trusted CAs. This will enable TLS against the Auth gRPC endpoint trusting only those CAs that are provided.

In constrained environments, sometimes it makes sense to run Clients service as a standalone to reduce network traffic and simplify deployment. This means that Clients service operates only using a single user and is able to authorize it without gRPC communication with Auth service. To run service in a standalone mode, set Clients_STANDALONE_EMAIL and Clients_STANDALONE_TOKEN.

Usage

For more information about service capabilities and its usage, please check out the API documentation.

Documentation

Overview

Package clients contains the domain concept definitions needed to support SuperMQ clients service functionality.

This package defines the core domain concepts and types necessary to handle clients in the context of a SuperMQ clients service. It abstracts the underlying complexities of user management and provides a structured approach to working with clients.

Copyright (c) Abstract Machines SPDX-License-Identifier: Apache-2.0

Index

• Constants
• Variables
• func AvailableActions() []roles.Action
• func BuiltInRoles() map[roles.BuiltInRoleName][]roles.Action
• func NewExternalOperationPerm() svcutil.ExternalOperationPerm
• func NewExternalOperationPermissionMap() map[svcutil.ExternalOperation]svcutil.Permission
• func NewOperationPerm() svcutil.OperationPerm
• func NewOperationPermissionMap() map[svcutil.Operation]svcutil.Permission
• func NewRolesOperationPermissionMap() map[svcutil.Operation]svcutil.Permission
• type Cache
• type Client
  • func (client Client) MarshalJSON() ([]byte, error)
• type ClientRepository
• type ClientsPage
• type Connection
• type Credentials
• type MembersPage
• type Metadata
• type Page
• type Repository
• type Role
  • func ToRole(status string) (Role, error)
  • func (r Role) MarshalJSON() ([]byte, error)
  • func (cs Role) String() string
  • func (r *Role) UnmarshalJSON(data []byte) error
• type Service
  • func NewService(repo Repository, policy policies.Service, cache Cache, ...) (Service, error)
• type Status
  • func ToStatus(status string) (Status, error)
  • func (s Status) MarshalJSON() ([]byte, error)
  • func (s Status) String() string
  • func (s *Status) UnmarshalJSON(data []byte) error

Constants

const (
	ClientUpdate           roles.Action = "update"
	ClientRead             roles.Action = "read"
	ClientDelete           roles.Action = "delete"
	ClientSetParentGroup   roles.Action = "set_parent_group"
	ClientConnectToChannel roles.Action = "connect_to_channel"
	ClientManageRole       roles.Action = "manage_role"
	ClientAddRoleUsers     roles.Action = "add_role_users"
	ClientRemoveRoleUsers  roles.Action = "remove_role_users"
	ClientViewRoleUsers    roles.Action = "view_role_users"
)

const (
	OpViewClient svcutil.Operation = iota
	OpUpdateClient
	OpUpdateClientTags
	OpUpdateClientSecret
	OpEnableClient
	OpDisableClient
	OpDeleteClient
	OpSetParentGroup
	OpRemoveParentGroup
	OpConnectToChannel
	OpDisconnectFromChannel
)

const (
	DomainOpCreateClient svcutil.ExternalOperation = iota
	DomainOpListClients
	GroupOpSetChildClient
	GroupsOpRemoveChildClient
	ChannelsOpConnectChannel
	ChannelsOpDisconnectChannel
)

External Operations.

const (
	Admin = "admin"
	User  = "user"
)

String representation of the possible role values.

const (
	Disabled = "disabled"
	Enabled  = "enabled"
	Deleted  = "deleted"
	All      = "all"
	Unknown  = "unknown"
)

String representation of the possible status values.

const (
	ClientBuiltInRoleAdmin = "admin"
)

Variables

var (
	// ErrEnableClient indicates error in enabling client.
	ErrEnableClient = errors.New("failed to enable client")

	// ErrDisableClient indicates error in disabling client.
	ErrDisableClient = errors.New("failed to disable client")
)

Functions

func AvailableActions

func AvailableActions() []roles.Action

func BuiltInRoles

func BuiltInRoles() map[roles.BuiltInRoleName][]roles.Action

func NewExternalOperationPerm

func NewExternalOperationPerm() svcutil.ExternalOperationPerm

func NewExternalOperationPermissionMap

func NewExternalOperationPermissionMap() map[svcutil.ExternalOperation]svcutil.Permission

func NewOperationPerm

func NewOperationPerm() svcutil.OperationPerm

func NewOperationPermissionMap

func NewOperationPermissionMap() map[svcutil.Operation]svcutil.Permission

func NewRolesOperationPermissionMap

func NewRolesOperationPermissionMap() map[svcutil.Operation]svcutil.Permission

Types

type Cache

type Cache interface {
	// Save stores pair client secret, client id.
	Save(ctx context.Context, clientSecret, clientID string) error

	// ID returns client ID for given client secret.
	ID(ctx context.Context, clientSecret string) (string, error)

	// Removes client from cache.
	Remove(ctx context.Context, clientID string) error
}

Cache contains client caching interface.

type Client

type Client struct {
	ID          string      `json:"id"`
	Name        string      `json:"name,omitempty"`
	Tags        []string    `json:"tags,omitempty"`
	Domain      string      `json:"domain_id,omitempty"`
	ParentGroup string      `json:"parent_group_id,omitempty"`
	Credentials Credentials `json:"credentials,omitempty"`
	Metadata    Metadata    `json:"metadata,omitempty"`
	CreatedAt   time.Time   `json:"created_at,omitempty"`
	UpdatedAt   time.Time   `json:"updated_at,omitempty"`
	UpdatedBy   string      `json:"updated_by,omitempty"`
	Status      Status      `json:"status,omitempty"` // 1 for enabled, 0 for disabled
	Permissions []string    `json:"permissions,omitempty"`
	Identity    string      `json:"identity,omitempty"`
}

func (Client) MarshalJSON

func (client Client) MarshalJSON() ([]byte, error)

type ClientRepository

type ClientRepository struct {
	DB postgres.Database
}

type ClientsPage

type ClientsPage struct {
	Page
	Clients []Client
}

ClientsPage contains page related metadata as well as list.

type Connection

type Connection struct {
	ClientID  string
	ChannelID string
	DomainID  string
	Type      connections.ConnType
}

type Credentials

type Credentials struct {
	Identity string `json:"identity,omitempty"` // username or generated login ID
	Secret   string `json:"secret,omitempty"`   // password or token
}

Credentials represent client credentials: its "identity" which can be a username, email, generated name; and "secret" which can be a password or access token.

type MembersPage

type MembersPage struct {
	Page
	Members []Client
}

type Metadata

type Metadata map[string]interface{}

Metadata represents arbitrary JSON.

type Page

type Page struct {
	Total      uint64   `json:"total"`
	Offset     uint64   `json:"offset"`
	Limit      uint64   `json:"limit"`
	Name       string   `json:"name,omitempty"`
	Id         string   `json:"id,omitempty"`
	Order      string   `json:"order,omitempty"`
	Dir        string   `json:"dir,omitempty"`
	Metadata   Metadata `json:"metadata,omitempty"`
	Domain     string   `json:"domain,omitempty"`
	Tag        string   `json:"tag,omitempty"`
	Permission string   `json:"permission,omitempty"`
	Status     Status   `json:"status,omitempty"`
	IDs        []string `json:"ids,omitempty"`
	Identity   string   `json:"identity,omitempty"`
	ListPerms  bool     `json:"-"`
}

type Repository

type Repository interface {
	// RetrieveByID retrieves client by its unique ID.
	RetrieveByID(ctx context.Context, id string) (Client, error)

	// RetrieveAll retrieves all clients.
	RetrieveAll(ctx context.Context, pm Page) (ClientsPage, error)

	// SearchClients retrieves clients based on search criteria.
	SearchClients(ctx context.Context, pm Page) (ClientsPage, error)

	// RetrieveAllByIDs retrieves for given client IDs .
	RetrieveAllByIDs(ctx context.Context, pm Page) (ClientsPage, error)

	// Update updates the client name and metadata.
	Update(ctx context.Context, client Client) (Client, error)

	// UpdateTags updates the client tags.
	UpdateTags(ctx context.Context, client Client) (Client, error)

	// UpdateIdentity updates identity for client with given id.
	UpdateIdentity(ctx context.Context, client Client) (Client, error)

	// UpdateSecret updates secret for client with given identity.
	UpdateSecret(ctx context.Context, client Client) (Client, error)

	// ChangeStatus changes client status to enabled or disabled
	ChangeStatus(ctx context.Context, client Client) (Client, error)

	// Delete deletes client with given id
	Delete(ctx context.Context, clientIDs ...string) error

	// Save persists the client account. A non-nil error is returned to indicate
	// operation failure.
	Save(ctx context.Context, client ...Client) ([]Client, error)

	// RetrieveBySecret retrieves a client based on the secret (key).
	RetrieveBySecret(ctx context.Context, key string) (Client, error)

	RetrieveByIds(ctx context.Context, ids []string) (ClientsPage, error)

	AddConnections(ctx context.Context, conns []Connection) error

	RemoveConnections(ctx context.Context, conns []Connection) error

	ClientConnectionsCount(ctx context.Context, id string) (uint64, error)

	DoesClientHaveConnections(ctx context.Context, id string) (bool, error)

	RemoveChannelConnections(ctx context.Context, channelID string) error

	RemoveClientConnections(ctx context.Context, clientID string) error

	// SetParentGroup set parent group id to a given channel id
	SetParentGroup(ctx context.Context, cli Client) error

	// RemoveParentGroup remove parent group id fr given chanel id
	RemoveParentGroup(ctx context.Context, cli Client) error

	RetrieveParentGroupClients(ctx context.Context, parentGroupID string) ([]Client, error)

	UnsetParentGroupFromClient(ctx context.Context, parentGroupID string) error

	roles.Repository
}

Repository is the interface that wraps the basic methods for a client repository.

type Role

type Role uint8

Role represents Client role.

const (
	UserRole Role = iota
	AdminRole

	// AllRole is used for querying purposes to list clients irrespective
	// of their role - both admin and user. It is never stored in the
	// database as the actual Client role and should always be the largest
	// value in this enumeration.
	AllRole
)

Possible Client role values.

func ToRole

func ToRole(status string) (Role, error)

ToRole converts string value to a valid Client role.

func (Role) MarshalJSON

func (r Role) MarshalJSON() ([]byte, error)

func (Role) String

func (cs Role) String() string

String converts client role to string literal.

func (*Role) UnmarshalJSON

func (r *Role) UnmarshalJSON(data []byte) error

type Service

type Service interface {
	// CreateClients creates new client. In case of the failed registration, a
	// non-nil error value is returned.
	CreateClients(ctx context.Context, session authn.Session, client ...Client) ([]Client, error)

	// View retrieves client info for a given client ID and an authorized token.
	View(ctx context.Context, session authn.Session, id string) (Client, error)

	// ListClients retrieves clients list for a valid auth token.
	ListClients(ctx context.Context, session authn.Session, reqUserID string, pm Page) (ClientsPage, error)

	// Update updates the client's name and metadata.
	Update(ctx context.Context, session authn.Session, client Client) (Client, error)

	// UpdateTags updates the client's tags.
	UpdateTags(ctx context.Context, session authn.Session, client Client) (Client, error)

	// UpdateSecret updates the client's secret
	UpdateSecret(ctx context.Context, session authn.Session, id, key string) (Client, error)

	// Enable logically enableds the client identified with the provided ID
	Enable(ctx context.Context, session authn.Session, id string) (Client, error)

	// Disable logically disables the client identified with the provided ID
	Disable(ctx context.Context, session authn.Session, id string) (Client, error)

	// Delete deletes client with given ID.
	Delete(ctx context.Context, session authn.Session, id string) error

	SetParentGroup(ctx context.Context, session authn.Session, parentGroupID string, id string) error

	RemoveParentGroup(ctx context.Context, session authn.Session, id string) error

	roles.RoleManager
}

Service specifies an API that must be fullfiled by the domain service implementation, and all of its decorators (e.g. logging & metrics).

func NewService

func NewService(repo Repository, policy policies.Service, cache Cache, channels grpcChannelsV1.ChannelsServiceClient, groups grpcGroupsV1.GroupsServiceClient, idProvider smq.IDProvider, sIDProvider smq.IDProvider) (Service, error)

NewService returns a new Clients service implementation.

type Status

type Status uint8

Status represents Client status.

const (
	// EnabledStatus represents enabled Client.
	EnabledStatus Status = iota
	// DisabledStatus represents disabled Client.
	DisabledStatus
	// DeletedStatus represents a client that will be deleted.
	DeletedStatus

	// AllStatus is used for querying purposes to list clients irrespective
	// of their status - both enabled and disabled. It is never stored in the
	// database as the actual Client status and should always be the largest
	// value in this enumeration.
	AllStatus
)

Possible Client status values.

func ToStatus

func ToStatus(status string) (Status, error)

ToStatus converts string value to a valid Client status.

func (Status) MarshalJSON

func (s Status) MarshalJSON() ([]byte, error)

Custom Marshaller for Client.

func (Status) String

func (s Status) String() string

String converts client/group status to string literal.

func (*Status) UnmarshalJSON

func (s *Status) UnmarshalJSON(data []byte) error

Custom Unmarshaler for Client.