IDP WebHook

The PlainID IDP Webhook enables IDP Token Enrichment, by dynamically enriching the IDP JWT with claims from the PlainID PDP response. After the IDP generates a JWT token allowing the user to log in, it reaches out to the Authorization Platform, requesting an authorization response to its query. The token is enriched with the decision based on organization-defined criteria such as which users (WHO) can access the specified Asset (WHAT) according to specific Conditions (WHEN). The JWT is enriched with this information and returned to the application, which then ALLOWS or DENIES the user access based not only on the identification of the user (for example password or user name) but also the rules and conditions defined in the organization's Authorization Policies.

This session-based enriched token provides several benefits to the organization. First and foremost is the seamless nature of the interaction between the user who wishes to log in to the Application, and the IDP, which needs to allow access based on specific Policies. These Policies are agnostic, meaning that the user (and even the Application itself) does not need to interact with (or even be aware of) the Platform's role in implementing the organization's Authorization requirements.

Token Enrichment Workflow Example

1. User requests to log into the Online Bank Portal.
2. The organization's Online Bank Portal application receives the login requests and sends a query to the IDP. 
3. The IDP sends a query to the PlainID IDP Webhook, which in turn queries the Policy Decision Point (PDP). Claims with the required values are then returned to the PlainID Webhook, which enriches the JWT token and returns it to the organization's IDP.
4. The enriched JWT is returned to the Application, which uses the information in the enriched token to either approve or deny access to the Application.

   PAA Prerequisites

   • A Policy Authorization Agent must be installed and running.
   • An Application must be defined.
     • Associate an Asset Type that manages the Claims with the Application
       • With the associated Scope (Client ID + ClientSecret) (this information is used to define the Hook in the IDP
       • claimKey and claimValue Attributes must be defined.
   • A Policy must be defined and the Application associated to it.
   • IDP Prerequisites: 
     • Existing application
     • At least 1 user associated with the application in the IDP
     • Rule (Access Policy Rule)

       ### Platform Prerequisites / Pre-Conditions
   

   • Existence of the following building blocks:
     • Claims Asset Type With the following attributes:

   Attribute Name	Attribute Properties	Notes
   claimKey	Name for request = claimKey	Must
   claimValue	Name for request= claimValue	Must

   • At least 1 asset defined (Internal/PlainId manager asset), e.g.:

   Asset name	claimKey	claimValue
   Portal Administrator	claimPortalRole	Administrator
   Senior Department Manager	departmentManagerLevel	Senior

   • Identity Attributes
     • The Name for request must match the name of the attribute in the source
   • Optional - Add/Define Asset Type Rulesets
   • Define an Application
     • Associate the “Claims” Asset Type with the Application
     • With the associated Scope (ClientID + ClientSecret)
     • This will be used to define the Hook in the IDP
   • Define a Policy
     • Associate the Application

   IDP Prerequisites

   • Existing application
   • At least 1 user associated with the application in the IDP
   • Inline Hook Okta or Rule Auth0

   IDP Webhook in the Policy Authorization Agent

   IDP Webhook Setup in the Policy Authorization Agent - For Kubernetes (Helm)

   Important

   If upgrading your PAA (Versions 5.2410 and above), ensure that your custom-values.yaml is updated according to the changes in configuration listed in the code block below. Note that your idp-webhook is enabled.

   Add the following section to the values-custom.yaml
   Note: In the example below we have 2 IDP Application configurations (“Bank Portal” and “Loans Approval”)

   idp-webhook:
     enabled: true
     replicaCount: 1
   # Allows you to add any config files to /app/config
     plainIDConfig:
       config.yaml:
         log:
           format: json
           level: trace
         http:
           port: 8080
           jwt:
             jwtBearerActive: false
             jwtIgnoreVerification: true
         management:
           port: ${MANAGEMENT_PORT:8081}
         server:
           name: idp-webhook
           auth:
             secret:
         apps:
           - Bank Portal:
               clientid: PPWZYCOMXGNTHMGO8CIT
               clientsecret: 94syzfIOJI48pfFRAPt6BbjA7HdlbdAY74gnWVrX
               entitytype: User
               tokentype: identity
               includeIdentity: true
               userid: $.identity.claims.sub
               claims:
                 plainid: $.response[*].access[?(@.resourceType == "assetExternal")].path
                 FirstName_identity: $.identity.attributes.first_name
   
           - Loan Approval:
               clientid: PXY8GCMDLPKSNAFDAA7A
               clientsecret: U4kt3WL2vZytHqB4oseSAWePGeS7p1JxIO0Bpas1
               entitytype: User
               tokentype: identity
               includeIdentity: false
               userid: $.identity.claims.sub
               claims:
                 plainid: $.response[*].access[?(@.resourceType == "portal-permissions")].path
                 FirstName_identity: $.identity.attributes.lastName
   
         secret: KQaIAMeiCfCQ02mdiVxxcJpKuvlWEG3GokoHtcmlaIqhvF4lxYPrL_B8UEoBl4FA
         runtime:
           host: http://10.xxx.xx.xx
           uri: /api/runtime/token/v3
           tenantPattern: "http://[tenant]-runtime.runtime"
           listenport: "8010"
           timeout: 3s
   

   Applications Parameters Information

   Attribute/Parameter	Description
   Application Name	The IDP Client name - must be an exact match
   clientid	Platform Scope Client ID
   clientSecret	Platform Scope Client Secret
   entitytype	The Identity Type (default User)
   tokentype	Which token will be used to return the claims: - Identity [Default] - Access
   includeIdentity	Request the PDP to include the Identity Attributes in the response Notice: In order to map identity attributes, the includeIdentity must be set to true
   userid	The JSON path to the user id Default $.identity.claims.sub
   claims	List of claims and the corresponding JSONPath mappings from the Platform PDP Response

   General Parameters

   Attribute/Parameter	Value	Description
   secret	secret	This Secret is used to allow the IDP to authenticate with the IDP Webhook endpoint
   log.level	Error
   runtime.host	<http://plainid-paa-uk.local>	The server K8s svc IP
   runtime.uri	/api/runtime/token/v3	Static value
   runtime.listenport	8080	The port that the IDP Webhook service will be listening to

   Mapping the PlainID Policy Decision Response to Claims

   Sample JSON Path Expressions:

   Expression	Description
   $.response[*].access[?(@.resourceType == "ProfileInformation")].attributes.BU	Get the Business Unit (BU) code from the ProfileInformation assets included in the PDP Response
   $.response[*].access[?(@.resourceType == "Accounts")].path	Get the asset id (path) from the Accounts Asset Type assets included in the PDP Response
   $.response[*].access[?(@.resourceType == "InternalIDP")].attributes.AttText[*]	Get a multi-value set of attributes from the InternalIDP Asset Type assets included in the PDP Response
   $.identity.attributes.user_role	Get the user_role attribute  from the identity included in the PDP Response Notice: To map identity attributes, the includeIdentity must be set to true