How it works/FAQ

Concepts

NGS is a global communications system built on NATS.io. It allows digital systems, services and devices to communicate through the exchange of messages. To connect to the system, users need a single worldwide accessible URL, connect.ngs.global, and their credentials. Once connected, messages are sent and received via subjects. A subject is a string that represents interest in data and supports wildcard matching for a rich and flexible way to direct message flow between your applications. See NATS subjects for more information.

NGS is powered by core NATS, an At-Most-Once delivery system supporting three basic communication patterns:

• Publish Subscribe
• Request/Reply
• Distributed Load Balanced Queue

Authentication and Authorization

When connecting to NGS, the system will identify the user associated with the credentials for your account. NGS uses a security mechanism where you do not give the system your private keys, only public keys. The keys are an encoded form of Ed25519 key used to represent identities in NATS, known as nkeys. The Nkey seeds generated by the signup process are SECRET. Do not share them with anyone you do not trust, they are yours and yours alone. If you lose them, you will lose access to your NGS account for that user, so be sure to back them up in a secure place. The NGS system never stores or even has access to your secret credentials. When you signed up the NGS tool created an Nkey keypair on your local computer that has never been shared with the NGS system. We will discuss credentials and the process in more depth in a following section. By default, users can send and receive messages on any subjects they chose. NGS allows fine-grained control of these authorizations however, and users can be updated easily to only be allowed to publish or subscribe on certain subjects through the NGS/NATS authorization primitives.

Creating Additional Users

You can add new users to your account through ngs add user command.

When you create a new user, an nkey pair (a public key and private seed) is generated to represent that user in NGS. This Nkey pair allows a user to prove that they are who they say they are. The user credentials will be signed for by the account owner, which is your default account that was created at signup. You can setup permissions for a user, set activation time, expiration time, and set other limits. For more information, use the ngs add user --help command.

Accounts

When you signed up with NGS, the NGS system created an account and default user for you. The account credentials were signed by the operator, in this case Synadia, and the account is the owner of the users we were creating above. Accounts define the subject space that users will operate in. More specifically, by default ONLY users in the same account can send and receive messages to each other. This provides a secure isolation context for your subject space.

Accounts and Sharing Options

NGS is a secure multi-tenant system. Many accounts will be present in the system at any given time and the default mode is that any messages sent from an account can only be received by users in the same account. However, there are ways to securely share data between accounts in an easy yet highly secure way.

Streams and Services

Streams and Services are concepts we introduce to define which data we would like to share. Services are endpoints where we can receive a request through a subscriber and respond with the appropriate answer. Streams are outbound event streams that result when a user publishes a message to a subject. Both of these can be exported for other users from a different account to access.

Exports and Imports

The way an account offers streams and services for use by other accounts is through an export. An export specifies which subject is being exported, whether it is a stream or a service, and if authorization is required by the account owner for another account to access. The way an account would consume these streams or services is through an import. An import specifies the source account, the subject and type of the import, and where the system will map the subject into the new accounts subject space. This allows the consuming account to maintain ownership and control over its own subject space, opening the door to decentralized account management easing the burden on operators. Lastly, if an export is not considered to be public, the source account must sign an authorization for the destination account, subject and type that is included, or referenced, in the destination account's import statement. Without authorization for non-public exports, the import will fail when checked by the NGS system, thus requiring mutual agreement for data to flow between accounts.

Stream Exports

To export a stream or service, add an export statement to the specified account.

This updates and uploads your token. If you publish messages to the “weather.CA” subject, any other NGS customer who has imported “weather.CA” can consume those messages.

Service Exports

This exposes a service for other NGS customers to import, allowing your account to send requests to "ip.geo".

There are more options for exporting streams and services, see ngs add export --help for more information.

Imports

On paid plans, you can import streams and services. There are imposed limits to how many, please check your plan type. Doing an import is accomplished through the ngs add import. You may be required to provide an authorization token if the export is not public.

There are more options for importing streams and services, see ngs add import --help for more information.

Additional Commands

The ngs utility can be used to add, remove, and edit users, imports, and exports. See ngs --help for more information. Note that while NGS is a general NATS utility, only commands related to signup, users, import, and exports will be supported on the Synadia operated global digital network.

Connecting an Application

Supported Clients use the standard NATS APIs, except there is a new credentials option available to connect with and accept a credentials file. This is required to connect to NGS. The credentials file is a chained file with both a user JWT and the seed/private Nkey for signing the challenge from the server.