This documentation supports the 22.2 version of BMC Helix Single Sign-On, which is available only to BMC Helix customers (SaaS). To view an earlier version, select the version from the Product version menu.

Notifying an external service about user authentication by using a webhook

Important

If you need to add webhooks for a realm, request BMC SaaS Operations to configure this feature.

Webhook is a method of augmenting or altering the behavior of a web page or web application with custom callbacks. If a webhook is added for the realm, BMC Helix SSO notifies the external service on passing the details of the authenticated user (or user groups) to the protected BMC application. This message is sent before a user session is created for the authenticated user. The external service is not notified if the end user is reauthenticated or redirected. In BMC Helix SSO, webhooks are used as a part of the login flow to notify an external service about user authentication through the following authentication types:

Related topics

Configuring-general-settings-for-a-realm

SAML-2-0-authentication

OpenID-Connect-authentication

Before you begin

As a SaaS administrator, you must first configure the OpenID Connect Issuer URL and generate a JWK; see Configuring-OAuth-2-0. 

To configure webhooks for SAML 2.0

  1. In the BMC Helix SSO Admin Console, edit the tenant, and enable the Webhooks on authentication response feature.
  2. Click Realm, and edit the realm to which you want to add a webhook.

  3. In the General tab, in the On Auth Webhook URL field, specify the webhook URL provided by the external service to which BMC Helix SSO sends messages on end-user authentication.

    For security reason, the webhook URL must differ from the localhost URL.

  4. Edit the realm to which you have added the webhook, click Authentication, and for SAML, specify Xpath 1.0 for group retrieval and validate it with the customer’s SAML assertion. 

    If the Xpath is not configured, the webhook will not have the groups attribute → "groups":[]. If the XPath is configured improperly, does not align with the customer's SAML assertion, or the customer's SAML is not configured, the groups attribute will have an empty array, which prevents identifying whether the user is missing a membership or groups or the user does not have an association with any group. If the XPath is invalid, BMC Helix SSO will not authenticate the user.

  5. Click Save.

To configure webhooks for OpenID Connect

  1. In the BMC Helix SSO Admin Console, edit the tenant, and enable the Webhooks on authentication response feature.
  2. Click Realm, and edit the realm to which you want to add a webhook.
  3. In the General tab, in the On Auth Webhook URL field, specify the webhook URL provided by the external service to which BMC Helix SSO sends messages on end-user authentication.
    For security reason, the webhook URL must differ from the localhost URL.
  4. Edit the realm to which you have added the webhook, click Authentication, and for OpenID Connect, specify Groups Claim Name—a name of the claim in id_token from which to extract end-user groups.
  5. Click Save.

Further considerations

The user is authenticated, and a session is created for them if the external service returns 200 or 201. If the external service returns a status code other than HTTP 200 or 201, BMC Helix SSO does not create a user session to prevent further user login to the protected BMC application.

A timeout limit of 10 seconds is applicable in the following cases:

  • BMC Helix SSO cannot connect with the external server.
  • The external service server does not respond after BMC Helix SSO authenticates a user.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*