Notifying an external service about user authentication by using a webhook

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.

To customize webhooks payload for SAML 2.0

As a SaaS administrator, you can configure a custom webhook payload based on extracted attributes from the SAML IdP.

A default webhook payload structure consists of the following predefined attributes:

A default webhook payload applies to the realm when the Webhook Claim field is empty.

When you set a new attribute, the list of predefined attributes will include its value and apply to a webhook payload.

If a new attribute matches an attribute name in the default payload, the existing attribute will replace the new one. In such a case, a webhook payload includes the value that BMC Helix SSO will pull based on XPath rules from the SAML IdP response.

You can select available values specified in the XPath field and set them as custom attributes for a webhook playload. For information about XPath and SAML IdP, see Configuring-advanced-functions-for-SAML-authentication.

The Webhook Claim field is a case-sensitive. If you specify "tenant" and "Tenant", the field will consider these values as different.

Before you begin

Webhooks on authentication response and Enable attribute extraction from SAML IdP options should be enabled for the particular tenant.

1. In BMC Helix SSO Admin Console, navigate to the Realms tab.
2. Create the new realm or open the appropriate realm for editing.
3. In the realm, click Authentication.
4. From the Authentication drop-down list, select SAML.
5. Navigate to the User attributes section and click Add. 
6. Specify all necessary fields.
7. In the Webhook Claim, specify an attribute to be used for a custom webhook payload. 
8. Click Save.