PingAM

Configure webhooks

Webhooks are used to send HTTP POST calls to a server with contextual information about an authenticated session when a predefined event occurs, for example, logging out.

Webhooks are used from within authentication trees by the Register Logout Webhook node.

Create a webhook

  1. In the AM admin UI, go to Realms > Realm Name > Authentication > Webhooks.

    1. To create a new webhook, select Create Webhook, specify a webhook name, and click Create.

    2. To edit an existing webhook, select the name of the webhook.

    Creating a new authentication webhook.

  2. Complete the fields as required:

    Url

    Specifies the URL to which the HTTP POST is sent when the event occurs.

    Body

    Specifies the body of the HTTP POST. You can send different formats by also setting the correct Content-Type header in the Header property, for example:

    • Form Data. Enter the body value in the format parameter=value&parameter2=value2, and set a Content-Type header of application/x-www-form-urlencoded.

    • JSON Data. Enter the body value in the format {"parameter":"value","parameter2":"value2"}, and set a Content-Type header of application/json.

    Headers

    Specifies any HTTP headers to add to the POST.

    To add a header, enter the name of the header in the Key field, and the value, and click Add (➕).

    To remove a header, click Delete (✖).

    The fields in a webhook support variables for retrieving values from the authenticated session after the user has successfully authenticated.

    Specify a variable in the following format:

    ${variable_name}

    To access the type of webhook event, use the WebhookEventType parameter key to return one of the following possible values:

    • LOGOUT

    • UPGRADE

    • DESTROY

    • MAX_TIMEOUT

    • IDLE_TIMEOUT

    For example, to retrieve the event type as a query parameter: &event=${WebhookEventType}

    You can use a variable to access custom properties added to the session with the Set Session Properties node as well as the following default session properties:

    Default Session Properties
    Property Example value Description

    AMCtxId

    22e73c81-708e-4849-b064-db29b68ef943-105372

    The audit ID for the session. This is logged as the trackingIds field in AM access audit logs.

    amlbcookie

    01

    The cookie that identifies the AM server that generated the session. For environments with multiple AM servers, this can be used for load balancer stickiness.

    authInstant

    2022-02-28T14:06:31Z

    The exact time that authentication completed.

    AuthLevel

    5

    The authentication level of the session, determined by the login mechanism used to create the session. For example, a tree can have an authentication level of 10.

    Step-up authentication is triggered if an authentication level specified by an agent or policy that is designed to protect a resource, is greater than or equal to the value of the AuthLevel session property.

    For more information, see Session upgrade.

    AuthType

    DataStore

    Not supported.

    CharSet

    UTF-8

    The character set for the session, set to UTF-8.

    clientType

    genericHTML

    The type of client, set to genericHTML.

    FullLoginURL

    /am/XUI/?realm=%2Falpha

    The full login URL, including query parameters.

    Host

    192.0.2.1

    The originating IP address of the authentication request.

    HostName

    192.0.2.1

    The host name that was used when the session was authenticated.

    IndexType

    service

    Based on the value of the authIndexValue query parameter during authentication. Typically, this is set to service.

    Locale

    en_US

    The session locale.

    loginURL

    /am/XUI

    The base login URL. A subset of FullLoginURL.

    OidcSid

    g0wmSpoAIwH6HAwCnurvRcfYqh4

    Unique session ID used by AM to determine whether OIDC ID tokens granted for the same client relate to the same session. This appears when Enable Session Management (storeOpsToken) is set to true in the OAuth 2.0 provider settings.

    Organization

    o=alpha,ou=services,dc=am,dc=example,dc=com

    The DN of the realm where authentication took place.

    Principal

    id=bjensen,ou=user,o=alpha,ou=services,dc=am,dc=example,dc=com

    The value of sun.am.UniversalIdentifier.

    Principals

    bjensen

    The username of the user. Not supported.

    Service

    Login

    The name of the tree that was used to authenticate this session.

    successURL

    /am/console

    The URL that was redirected to, upon a successful login request.

    sun.am.UniversalIdentifier

    id=bjensen,ou=user,o=alpha,ou=services,dc=am,dc=example,dc=com

    The DN of the user (username is lowercase).

    UserId

    bjensen

    The id value from the Principal property.

    UserProfile

    Required

    Can be one of: Required, Create, Ignore, or CreateWithAlias. Based on the value of the dynamicProfileCreation authentication configuration. Values other than Ignore indicates that user profile attributes were mapped based on the User Attribute Mapping to Session Attribute setting. See authentication configuration for details.

    Default: Required.

    UserToken

    bjensen

    The username.

    XUSRef

    8700f1a5-904e-4849-8b2b-cb25296ef453-291173

    If the cross-upgrade session reference property is enabled, this value identifies the session through its lifecycle. This is logged in the trackingIds field in AM audit logs for session creation and upgrade events.

Example webhook

The following figure shows an example webhook using variable substitutions:

Example authentication webhook.

Specifying a variable that’s not present in the authenticated session places the literal variable text in the HTTP POST, for example user=${UserId}, rather than user=bjensen.