Skip to content

Latest commit

 

History

History
184 lines (168 loc) · 7.21 KB

export-capability.md

File metadata and controls

184 lines (168 loc) · 7.21 KB
Raw
id title sidebar_label
export-capability
Export Capability
Export

Creating new capabilities happens by exporting a capability configuration through a membrane. You provide the configuration for the capability as input, and you get back the new capability as output.

To export a capability through a membrane, you make a POST request using the membrane's export capability. The request should include a JSON body that contains the uri or capability, along with other optional attributes.

Request parameters

Parameter Description
capability (mutually exclusive with uri) An already existing Capability URI to re-export through this particular membrane. If the membrane is revoked the original capability will not be revoked, only the capability created during this re-export and any of its descendants will be revoked.
uri (mutually exclusive with capability) Fully qualified URI, for example https://example.com/path/to/something
allowQuery (uri option) (Default: false) Optionally allow requester's URI query string to be appended to the uri in membrane request.
headers (uri option) Optional headers to include with the membrane request to the URI. Hop-by-hop headers will be ignored.
hmac (uri option) Optional selector for which signature scheme to use to sign membrane request to URI.
- aws4-hmac-sha256: Use AWS4-HMAC-SHA256 signature.
-- awsAccessKeyId: AWS Access Key Id to sign requests with.
-- region: AWS region capability is in.
-- service: AWS service capability is in.
-- secretAccessKey: AWS Secret Access Key to sign requests with.
- cap1-hmac-sha512: Use CAP1-HMAC-SHA512 signature.
-- key: Base64url encoded secret key bytes.
-- keyId: Secret key id.
method (uri option) Optional HTTP method to use in the membrane request to the URI. This overrides the method specified by the requester.
timeoutMs (uri option) Optional timeout in milliseconds to end idle connection between membrane and URI. Will be ignored if greater than membrane's configured internal timeout.
tls (uri option) TLS options.
- ca: Optionally, override default trusted Certificate Authorities (CAs). Default is to trust the well-known CAs curated by Mozilla. Mozilla's CAs are completely replaced when CA is explicitly specified using this option.
- cert: Optional certificate chain in PEM format.
- key: Optional private key in PEM format.
- rejectUnauthorized If not false, membrane request verifies responding server against the list of default trusted Certificate Authorities or supplied Certificate Authorities, if any.

Capabilities

Capability Description
export Capability to export through a membrane

Response

Response is a newly created capability. If something goes wrong, an error is returned.

Example request (capability)

NOTE: In these examples, $EXPORT_URI is the full Capability URI format of the export capability and $EXPORT_TOKEN is the fragment part of $EXPORT_URI that begins with "CBLTY-1".

$ capi membrane export --capability-to-export cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-GoqpcTT_GRVSyH-qYBGur2KnhZp7Tc06uEuFDk8Ma2e_XX1tUjLgtASB_I8SkVA4VZYcTkozC6PDdNkpIfMIjA --capability $EXPORT_URI

$ curl -XPOST \
    https://membrane.amzn-us-east-1.capability.io \
    -H "Authorization: Bearer $EXPORT_TOKEN" \
    -d '{"capability":"cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-GoqpcTT_GRVSyH-qYBGur2KnhZp7Tc06uEuFDk8Ma2e_XX1tUjLgtASB_I8SkVA4VZYcTkozC6PDdNkpIfMIjA"}'

const https = require("https");
const options =
{
    hostname: "membrane.amzn-us-east-1.capability.io",
    method: "POST",
    headers:
    {
        authorization: "Bearer $EXPORT_TOKEN"
    }
};
const req = https.request(options, resp =>
    {
        console.log(resp.statusCode); // 201
        resp.on("data", data => process.stdout.write(data.toString()));
        resp.on("end", () => process.stdout.write("\n"));
    }
);
req.on("error", error => console.error(error, error.stack));
req.write(JSON.stringify(
    {
        capability: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-GoqpcTT_GRVSyH-qYBGur2KnhZp7Tc06uEuFDk8Ma2e_XX1tUjLgtASB_I8SkVA4VZYcTkozC6PDdNkpIfMIjA"
    }
));
req.end();
const CapabilitySDK = require("capability-sdk");
const membrane = new CapabilitySDK.Membrane();
membrane.export(
    "$EXPORT_URI",
    {
        capability: "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-GoqpcTT_GRVSyH-qYBGur2KnhZp7Tc06uEuFDk8Ma2e_XX1tUjLgtASB_I8SkVA4VZYcTkozC6PDdNkpIfMIjA"
    },
    (error, resp) =>
    {
        if (error)
        {
            console.error(error, error.stack);
            return;
        }
        console.log(resp);
    }
);

Example request (uri)

NOTE: In these examples, $EXPORT_URI is the full Capability URI format of the export capability and $EXPORT_TOKEN is the fragment part of $EXPORT_URI that begins with "CBLTY-1".

$ capi membrane export \
    --uri https://www.example.com \
    --header "TenantID: tenant17" \
    --method DELETE \
    --capability $EXPORT_URI

$ curl -XPOST \
    https://membrane.amzn-us-east-1.capability.io \
    -H "Authorization: Bearer $EXPORT_TOKEN" \
    -d '{"uri":"https://www.example.com","headers":{"TenantID":"tenant17"},"method":"DELETE"}'

const https = require("https");
const options =
{
    hostname: "membrane.amzn-us-east-1.capability.io",
    method: "POST",
    headers:
    {
        authorization: "Bearer $EXPORT_TOKEN"
    }
};
const req = https.request(options, resp =>
    {
        console.log(resp.statusCode); // 201
        resp.on("data", data => process.stdout.write(data.toString()));
        resp.on("end", () => process.stdout.write("\n"));
    }
);
req.on("error", error => console.error(error, error.stack));
req.write(JSON.stringify(
    {
        uri: "https://www.example.com",
        headers:
        {
            TenantID: "tenant17"
        },
        method: "DELETE"
    }
));
req.end();
const CapabilitySDK = require("capability-sdk");
const membrane = new CapabilitySDK.Membrane();
membrane.export(
    "$EXPORT_URI",
    {
        uri: "https://www.example.com",
        headers:
        {
            TenantID: "tenant17"
        },
        method: "DELETE"
    },
    (error, resp) =>
    {
        if (error)
        {
            console.error(error, error.stack);
            return;
        }
        console.log(resp);
    }
);

Example response

{
    "capability": "cpblty://membrane.amzn-us-east-1.capability.io/#CPBLTY1-Vs8axPY96csXT6f7Jx_YhsyxjqsDxnIzytgtfmOHDoyIm6gDf-sjWgv-9OwufgDZAeLIGfHA2X8F-bkEXMuyMA"
}