Web hooks

Web hooks make the OneWelcome Identity Platform extendable by allowing you to change certain behaviors that it provides.

User details web hook

The user details customization web hook is identity-centric, meaning that it focuses only on user-related information. Modifying access control is out of scope.

To get a better understanding, consider the following scenarios:

1. There is another service that is a source of user-related information. The returned attributes are complementary to what is provided by the configured identity provider instance.

2. The client expects certain claims to be provided in a sophisticated format, regardless of whether it is related to the claim name or how the value is represented.

3. There is a need for a dynamic (based on specific factors or state) reduction of some of the user-related information that is provided to the clients.

User details web hook specification

The web hook input parameters include:

• identity of the user
• set of requested scopes
• all available user-related claims
• web hook context (optional custom parameters), such as 'on_behalf_of' or 'on_behalf_of_type', when integrating with an externalized authorization product

Based on the above information, the web hook is allowed to filter, change, and introduce new user claims.

The following claims are considered protected and are not allowed to be modified:

• iss
• aud
• verified_claims
• sub
• urn:onegini.com:oidc:*
• group_permissions

The web hook is executed before the ID token and user-information response creation. This way, the OneWelcome Identity Platform can feed the implementor all available information and ensure a deterministic result.

User details web hook configuration

Before the web hook can be used, a few configuration steps are required. First, you need to provide the details about where the web hook API can be reached, including the authentication details. When that's available, you can link the just-defined web hook instance to your client.

Define a user details web hook instance

To define a new web hook instance, log in to the OneWelcome Identity Platform admin console and navigate to the Configuration > System > Web Hooks tab. Next, select the Add Web Hook Configuration option and provide the required information:

• Define the name for the new web hook.

• Choose the User Details Customization type.

• Set the base URL. The base URL is concatenated with the web hook path that's defined in the API contract. For example, setting https://hooks.onewelcome.com, the OneWelcome Identity Platform calls the location: https://hooks.onewelcome.com/v1/customize-user-details.

• Choose the desired authentication scheme.

When done, save the configuration and proceed to your client configuration page.

Update the client configuration

Due to its characteristics, it only makes sense to configure the user-details customization web-hook with clients that are acting as OpenID Connect (OIDC) Relying Parties (RPs).

The web hook can be configured for both dynamic (represented by mobile applications) and static (usually represented by web apps or portals) clients. Depending on the type of client that you want to configure, navigate to Configuration > App Configuration > Applications or Configuration > Web clients respectively.

The web hook configuration is available at the OpenID Connect configuration page that is shown only after enabling the openid scope for that client.

Access token web hook

The access token web hook enables access control manipulation. The hook allows you to make a few operations, such as reducing the scopes that are associated with the grant that is created as part of the flow in which it is executed. Another operation allows adding claims to the access token. It can also determine whether a user is authorized in certain scenarios.

To get a better understanding, consider a scenario where the scopes are used to represent active subscriptions. Their validity changes over time, therefore you have the ability to actively validate and remove scopes that are not available for a particular user or client at a particular moment.

Access token web hook specification

The web hook input parameters include:

• identity of the user (if present)
• information about the client that was used to request the token
• set of requested scopes
• all available user-related claims
• execution context that includes the client IP address and the endpoint that it was triggeredBy, such as /oauth/authorize, /oauth/token, /oauth/v1/token, or /oauth/api/v1/token/introspect
• hook context (optional custom parameters), such as 'on_behalf_of' or 'on_behalf_of_type' when integrating with an Externalized Authorization product

Based on the above information, the web hook is allowed to remove an arbitrary number of scopes and return additional claims.

If all of the requested scopes are removed, the OneWelcome Identity Platform fails either the authorization or the token flow.

The web hook is executed before any access grant or token is created. This ensures that the access to potentially forbidden resources is not possible.

An example request and response for this hook might look as follows:

{
  "httpRequest": {
    "method": "POST",
    "path": "/v1/customize-access-token",
    "headers": {
      "Authorization": [
        "Basic aG9vazpob29r"
      ]
    },
    "body": {
      "type": "JSON",
      "json": {
        "user": {
          "id": "myUserId22700111101"
        },
        "client": {
          "id": "client"
        },
        "scopes": [
          "profile",
          "email"
        ],
        "userClaims": {
          "name": "John"
        },
        "executionContext": {
          "ipAddress": "127.0.0.1",
          "triggeredBy": "/oauth/authorize"
        }
        "contextCustomParams": {
          "on_behalf_of": [
            "user"
          ]
        }
      }
    }
  },
  "httpResponse": {
    "statusCode": 200,
    "headers": {
      "content-type": [
        "application/json"
      ]
    },
    "body": {
      "type": "JSON",
      "json": {
        "removeScopes": [
          "email"
        ],
        "additionalClaims": {
          "name": "John"
        },
        "authorized": true
      }
    }
  }
}

Access token web hook configuration

Before the web hook can be used, a few configuration steps are required. First, you need to provide the details about where the web hook API endpoint can be reached, including the authentication details. When that's available, you can link the just-defined web hook instance to your client.

Define an access token web hook instance

To define a new web hook instance, log in to the OneWelcome Identity Platform admin console and navigate to Configuration > System > Web Hooks tab.

Next, select Add Web Hook Configuration option and provide the following information:

• Define the name for the new web hook.

• Select Customize Access Token type.

• Set the base URL. The base URL is concatenated with the web hook path that's defined in the API contract. For example, by setting https://hooks.onewelcome.com the OneWelcome Identity Platform calls the following location https://hooks.onewelcome.com/v1/customize-access-token.

• Select the desired authentication scheme

When you're done, save the configuration and proceed to your client configuration page.

Update client configuration

The customized access token web hook can be configured with any OAuth client type. Depending on your choice, navigate to Configuration > App Configuration > Applications or Configuration > Web clients respectively. The web hook configuration is available in the Scopes section.