Notifying an external service about user authentication by using a webhook

Webhooks are 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 Helix application. This additional information 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 OpenID Connect and SAML 2.0 authentication types. To enable external services to receive user authentication data from the OpenID Connect or SAML 2.0 identity providers, the administrator must add the webhooks for the external services to receive user information.

To add a webhook for OpenID Connect

In the BMC Helix SSO Admin Console, click Edit against the tenant where you want to add the webhook and enable Webhooks on authentication response.
Save your change.
In Realm, and edit the realm to which you want to add a webhook.
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 should send additional information about end-user authentication.
For security reasons, the webhook URL must differ from the localhost URL.
(Only if you want to have groups in the default webhook payload) Edit the realm to which you have added the webhook, click Authentication, select OIDC, specify Groups Claim Name—a name of the claim in the ID Token from which to extract end-user groups.
Save your changes.

To customize a webhook payload for OpenID Connect

As a SaaS administrator, you can extend the default webhook payload that consists of the following predefined attributes:

{
"login": "someLogin",
"groups": ["group1","group2"],
"realm": "someRealm",
"tenant": "tenantInRealm"
}

Scenario

Apex Global is a financial services company that uses BMC Helix products. To authenticate employees, BMC Helix SSO uses OpenID Connect. The default payload gives only basic information about users, but the Ops team wants to retrieve more information. Hence, the administrator adds other attributes, such as user name, authentication time, and email.

To add custom attributes to user data extracted from the OpenID Connect IdP, configure a webhook by following these steps:

Go to the Realm tab, create a new realm, or open the existing one for editing.
In the realm, click Authentication, and from the list of authentications, select OIDC.
Go to the User attributes from ID Token section and click Add.
Specify all the necessary fields:
- Name (required)—A name under which the custom claim is stored in the session.
- Type—A type of the claim as specified in the JWT token (String, Boolean, Array, or Object).
- Claim (required)—A custom claim as specified in the JWT token (depends on ID Token's structure; for example, preferred_username) that you want to add to the payload.
- Webhook Claim—An attribute to be used for a custom webhook payload. This field is case-sensitive: if you specify "tenant" and "Tenant", the field will consider these values as different.
Save your changes.

Important

In rare cases when an IdP does not send an ID Token, authentication can still proceed if you add custom attributes to the User attributes from userinfo endpoint section. The fields are the same as those in User attributes from ID Token.

If no custom attributes are provided, the default payload is transferred to an external service. When you set an additional attribute, its value will be included in the list of predefined attributes and added to a webhook payload.

Custom webhook claims override default claims if they share the same name and are mapped through the OpenID Connect realm to an ID Token claim.

To add a webhook for SAML 2.0

In the BMC Helix SSO Admin Console, click Edit against the tenant where you want to add the webhook and enable Webhooks on authentication response.
Save your change.
In Realm, and edit the realm to which you want to add a webhook.
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 should send additional information about end-user authentication.
For security reasons, the webhook URL must differ from the localhost URL.
(Only if you want to have groups in the default webhook payload) Edit the realm to which you have added the webhook, click Authentication, select SAML, specify Xpath 1.0 for group retrieval, and validate it with the customer’s SAML 2.0 assertion.

If the Xpath is not configured, the webhook will not have the groups attribute. If the XPath is configured incorrectly, does not align with the customer's SAML 2.0 assertion, or the customer's SAML 2.0 is not configured, the groups attribute will have an empty array. It will prevent 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.

6. Save your changes.

To customize a webhook payload for SAML 2.0

As a SaaS administrator, you can extend the default webhook payload that consists of the following predefined attributes:

{
"login": "userLogin",
"groups": ["group1","group2"],
"realm": "mainRealm",
"tenant": "tenantInRealm"
}

Scenario

To add custom attributes to user data extracted from the SAML 2.0 IdP, follow these steps:

Enable attribute extraction from SAML IdP for the particular tenant; see Configuring advanced functions for SAML authentication.
Go to the Realm tab, create a new realm, or open an existing realm for editing.
In the realm, click Authentication, and from the list of authentications, select SAML.
Go to the User attributes section and click Add.
Specify all the necessary fields:
- Name (required)—A name under which the custom claim is stored in the session.
- Type—A type of the claim as specified in the JWT token (Number, String, or StringArray).
- XPath (required)—Select the values specified in the XPath field and set them as custom attributes for a webhook payload.
- Default—A static value to be added to the payload if the XPath rule does not extract any data from the SAML 2.0 response.
- Webhook Claim—An attribute to be used for a custom webhook payload. This field is case-sensitive: if you specify tenant and Tenant, the field will consider these values as different.
Save your changes.

Important

If a custom attribute has the same name as one of the default attributes, the default attribute takes priority and overwrites the custom one. In this case, a webhook payload will include the value extracted from the SAML 2.0 IdP by using the XPath rules defined by BMC Helix SSO.

Further considerations

If the external service returns 200 or 201, the user is authenticated, and a session is created for the user. 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 SSOcannot connect with the external server.
The external service server does not respond after BMC Helix SSO authenticates a user.