Identity Platform (IdP) Setup

Integrating to your identity platform requires defining the environment variables specified below in your docker-compose file.

Update the Docker Compose File #

The following configurations in the Docker Compose File need to be aligned with your IdP.

Issuer URI #

The URI identifying your IdP (supporting OpenID Connect) must be configured in the Docker Compose File. webhookie uses the Issuer URI to validate the JWT’s it receives. See Docker Compose File Configurations for more details.

WH_IAM_ISSUER_URI=https://webhookie.au.auth0.com/

JWT Key Set URI #

The JWT Key Set URI provided by your IdP must be configured in the Docker Compose File. webhookie uses the JWT Key Set URI to download the public keys from your IdP (supporting OpenID Connect) to verify the JWTs it receives. See Docker Compose File Configurations for more details.

WH_IAM_JWK_SET_URI=https://webhookie.au.auth0.com/.well-known/jwks.json

JWS Algorithm #

The JWS Algorithm that is used to sign the JWTs sent from IdP must be configured in the Docker Compose File. webhookie uses the JWS Algorithm to verify the JWTs it receives. See Docker Compose File Configurations for more details.

WH_IAM_JWS_ALG=RS256

webhookie API #

The webhookie backend service (API) must be set up in your IdP and the identifier for the API must be configured in the Docker Compose File. This is the identifier that must appear in the Audience (aud) claim in the JWT. webhookie uses this identifier to validate the JWTs it receives. See Docker Compose File Configurations for more details.

WH_SECURITY_AUD=http://localhost:8000

Client ID #

The webhookie portal must be set up in your IdP as a Single Page Web Application (SPA). Once setup you should have a client ID that must then be configured in the Docker Compose File. The client ID is used for login purposes. See Docker Compose File Configurations for more details.

WH_SECURITY_CLIENT_ID=nvKDmIK9Q5Zw1UKwpON8LE3tg9vZcXb4

JWT Claims #

Entity #

The entity claim identifies the entity for which this user represents. The entity could map to a company or alternatively could be made as granular as required. The entity claim is used by webhookie for authorization purposes which include:

  • Managing Applications – Applications, in webhookie, group callbacks and can be managed by a user with the WH_CONSUMER role as long as they belong to the same entity as the user that created the Application.
  • Authorized Subscribers – Authorized subscribers are a concept that allows only entities mentioned in the wh-authorized-subscriber header of an event to receive it (even if many other subscribers are subscribed to the same topic).

The entity claim must be mapped in the Docker Compose File to the claim in your JWT that identifies a users entity. See Docker Compose File Configurations for more details.

WH_SECURITY_ENTITY_JSON_PATH=$$['https://webhookie.com/entity']

Roles #

webhookie has 3 roles that need to be set up in your IdP. These are:

  • WH_ADMIN – can manage the instance, setup consumer and provider groups, whitelabeling and can see all traffic and subscriptions.
  • WH_CONSUMER – can create subscriptions to webhooks that are public or accessible to the consumer groups that the user belongs to. Learn more about consumer groups here.
  • WH_PROVIDER – can create webhooks and manage webhooks that they are authorized to manage based on the provider groups that the user belongs to. Learn more about provider groups here.

If you have standards for role names in your organization you can map your role names to these webhookie roles – see instructions. (to be documented)

Once the roles have been created they need to be assigned to your users.

The role claim must be mapped in the Docker Compose File to the claim in your JWT that identifies the roles that the user has.

WH_SECURITY_ROLES_JSON_PATH=$$['https://webhookie.com/roles']

Note by default you can automatically assign the WH_CONSUMER role to all your authenticated users with the WH_SECURITY_AUTO_ASSIGN_CONSUMER_ROLE configuration in the docker compose file.

WH_SECURITY_AUTO_ASSIGN_CONSUMER_ROLE=true

Groups #

There are two types of groups in webhookie which are the Consumer Groups and the Provider Groups.

Consumer groups control who gets access to discover and subscribe to webhooks.

Provider groups control who gets access to manage webhook APIs.

Consumer and Provider groups are created in webhookie by a WH_ADMIN user and they must be mapped to a group in the IdP.

The group claim must be mapped in the Docker Compose File to the claim in your JWT that identifies the groups that the user has. See Docker Compose File Configurations for more details.

WH_SECURITY_GROUPS_JSON_PATH=$$['https://webhookie.com/groups']

Powered by BetterDocs