NGS
Cross-Account Service Share
Using the add export
, generate activation
, and add import
commands of the nsc
tool, a service may be made available to other accounts.
Note: A service provider may choose to make their service available to any account in NGS (public export) or to selected accounts only (private export). Private export is shown.
Payment Service Scenario
For illustration, we consider a payment service (within ACCTA) exposing multiple retail payment operations including payment tender. Payment tender is an API that takes tender requests on the subject retail.v1.payment.tender
and replies with a response message indicating the result of tender.
The payment service is leveraged by multiple API client applications, including a point-of-sale checkout application that lives in ACCTB. The steps below show how to grant ACCTB access to use the tender API in its checkout application.
See also ngs-xacct-demo/service for scenario scripts.
As the API provider account (ACCTA)
Implement and start your service
You may use the NATS command-line tool to provide a mock Payment service that implements a Tender operation. The (optional) --queue
parameter allows you to start multiple load-balanced services.
nats reply --context ACCTA --queue payment-responder retail.v1.payment.tender 'Payment tendered!'
08:48:36 Listening on "retail.v1.payment.tender" in group "payment-responder"
Note: This is an optional step. Cross-account grants may be made at any time and do not depend on a running service.
Make your Payment service eligible to be visible to other accounts
Add a private export of the Payment service that responds to request messages on subject retail.v1.payment.>
using the nsc add export
command:
nsc add export --private --name PAYMENTAPI-GRANT-SERVICE --account ACCTA --subject 'retail.v1.payment.>' --service
Note: an export only makes a subject eligible to be imported into another account's namespace. Other accounts must explicitly import the subject. If the export is private (as here), other accounts must be in possession of an import grant activation token generated and provided by the exporter.
Explicitly allow ACCTB access to invoke the Payment service
Generate an import grant activation token for ACCTB using the nsc generate activation
command:
nsc generate activation --output-file PAYMENTAPI-GRANT-SERVICE-ACCTB.tok --account ACCTA --subject 'retail.v1.payment.>' --target-account AD7T74QPICDLJYKEJQ37RKP2VXUJYUUIHZ7XMGMWFEOZNKVO3VBF46F7
Note: ACCTA must know ACCTB's NGS public key
Provide the generated token file to the ACCTB owner.
As the API using account (ACCTB)
Accept access to the ACCTA Payment service
Add an import of the Payment service using the grant activation token provided by the ACCTA owner and the nsc add import
command:
nsc add import --token PAYMENTAPI-GRANT-SERVICE-ACCTB.tok --account ACCTB --name PAYMENTAPI-GRANT-SERVICE --local-subject 'retail.v1.payment.>'
Note: In this example, the ACCTB owner is electing to make the Payment service visible to ACCTB users at retail.v1.payment.>
but the local subject need not be the same.
Make a client request to tender payment
You may use the NATS command-line tool to provide a mock Payment client that requests a Tender operation.
nats request --context ACCTB retail.v1.payment.tender 'Tender my payment please!'
08:49:23 Sending request on "retail.v1.payment.tender"
08:49:23 Received on "_INBOX.qH22EvqBXH70dpuV4E6oWJ.iGVnfLLO" rtt 48.544434ms
Payment tendered!
Completing the scenario, ACCTA would see the following output at the mock Payment service:
08:49:23 [#0] Received on subject "retail.v1.payment.tender":
08:49:23 Nats-Request-Info: {"acc":"AD7T74QPICDLJYKEJQ37RKP2VXUJYUUIHZ7XMGMWFEOZNKVO3VBF46F7","rtt":88255126}