Skip to main content
Version: v5.1

Authorization

Overview#

Some webhook type subscriptions require an authorization method. This chooses the authentication logic and ensures that any password or secret value is stored securely using Passport Service secrets.

Note: All authorization methods store secret values using the Passport Service secrets feature. For more information, see the IafPassSvc JavaScript API page.

Authorization properties#

When you create an authorization, the following properties are supported:

  • _namespaces: A string array, which must contain a single item, which is the owning namespace for this trigger. Te user must have the create permissions in this namespace for the IRN notificationsvc:trigger:*
  • _name: An immutable user-friendly name that must be unique within the namespace.
  • _description: An optional description.
  • _type: The authorization type, which can be one of the following:
    • BASIC: HMAC HTTP Basic authorization (username, password)
    • HMAC: HMAC based authorization
    • API_KEY: A custom secret value added to a user-configurable header

Note: For more information on HMAC, refer to this HMAC explanation.

The rest of the properties available for a authorization depend on the value of the _type property.

Properties: _type = BASIC#

When _type is BASIC the following properties are supported:

  • _basic._username: The basic username
  • _basic._password._name: The name of the secret that contains the basic password in the Passport Service. The secret value must match the namespace and the name specified here.

When the webhook request is made, HTTP Basic authorization will be added, as described here: Basic Access Authentication.

Properties: _type = HMAC#

When _type is HMAC the following properties are supported:

  • _hmac._apiKey: The API key
  • _hmac._secretKey._name: The name of the secret that contains the HMAC secret key in the Passport Service. The secret value must match the namespace and the name specified there.

When the webhook request is made, HMAC authentication will be added. Headers will be added as follows:

Authorization: HMAC <apiKey>:<HMAC signature>X-Timestamp: <request timestamp>

Properties: _type = API_KEY#

When _type is API_KEY the following properties are supported:

  • _apiKey._header: The name of the header that the API key will be sent in
  • _apiKey._value._name: The name of the secret that contains the API key key in the Passport Service. The secret value must match the namespace and the name specified here.

When the webhook request is made, the API key value will be sent in the user-specified header.

Once an authorization is created, the following properties can be edited:

  • _description
  • _type (and all type-specific properties)

API examples#

How to create an authorization#

To create a HMAC authorization, with a secret value stored in the Passport Service, refer to the sample code below. 

const apiKey = "<my api key>";const secretKey = "<my secret key>";const secrets = await IafPassSvc.createSecrets([   {      _name: "HMAC_SECRET_KEY",      _value: secretKey,      _namespaces: project._namespaces,      _description: "HMAC secret value",      _userType: `system_${ctx._nsfilter}_secrets`   }], ctx);const authorization = await IafNotification.createAuthorization({   _namespaces: project._namespaces,   _name: "HMAC authorization",   _type: "HMAC",    _hmac: {      _apiKey: apiKey,      _secretKey: {         _name: "HMAC_SECRET_KEY"      }   }}, ctx);

How to update an authorization#

To update the API key and secret key of a HMAC authorization, refer to the sample code below. 

const newApiKey = "<my api key>";const newApiKey = "<my api key>";const newSecretKey = "<my secret key>";const secrets = await IafPassSvc.createSecrets([   {      _name: "NEW_HMAC_SECRET_KEY",      _value: newSecretKey,      _namespaces: [         project._namespaces      ],      _description: "New HMAC secret value",      _userType: `system_${ctx._nsfilter}_secrets`   }], ctx);const authorization = await IafNotification.updateTrigger(authorization._id, {   _hmac: {      _apiKey: newApiKey,      _secretKey: {         _name: "NEW_HMAC_SECRET_KEY"      }   }}, ctx);

How to list authorizations#

To list authorizations, you must provide a query. The query must include at a minimum, a set of namespaces for which the calling user has the READ permission.

To query for authorizations in your project, refer to the sample code below.

const triggers = await IafNotification.listAuthorizations({   namespaces: project._namespaces}, ctx);

The following query properties are supported, which map to the same properties used when creating/updating templates:

  • namespaces
  • name
  • type `

How to delete an authorization#

To delete an authorization, refer to the sample code below. 

await IafNotification.deleteAuthorization(authorization._id, ctx);