Skip to content

IG Scripts

Jump to bottom
Dan Badham edited this page Dec 6, 2023 · 39 revisions

The prebuilt ScriptableFilters and ScriptableHandlers for IG are located in the secure-api-gateway-ob-uk repository. You can access them by navigating to config > 7.2.0 > securebanking > ig > scripts > groovy.

These ScriptableFilters and ScriptableHandlers are used in the prebuilt routes alongside OOTB filters and handlers.

ScriptableFilters

AddDetachedSig

This filter adds a detached signature to the HTTP response.

  • Filter source: AddDetachedSig.groovy
  • Process type: RESPONSE
  • Filter processing:
    • The detached signature is a signed JWT with the response entity as the payload. The JWT is added as a response header with the payload removed.
    • If there is an error creating the signed JWT or the detached signature has the wrong number of dots, an Internal Server Error is returned.

AddGatewayAuthorization

This filter adds the gateway access token to the downstream request.

  • Filter source: AddGatewayAuthorization.groovy
  • Process type: REQUEST
  • Filter processing:
    • Copies the IG bearer token to the token request so that it is accessible from the Identity Cloud or AM token modification script.
    • If token request authorization isn't available for whatever reason, an Internal Server Error is returned.

ApiClientRoleCheck

This filter ensures the client certificate includes the required AISP or PISP role for the current route; the role type is configured in the routeArgRole parameter.

  • Filter source: ApiClientRoleCheck.groovy
  • Process type: REQUEST
  • Filter processing:
    • Checks the transport certificate for the roles appropriate to the request.
    • Retrieves the client certificate from the attributes context - clientCertificate.roles object:
      • If the configured role matches the ones from the client certificate roles, the processing is allowed to continue.
      • If there are no roles found on the client certificate, a Bad Request response is returned.
      • If the configured role doesn't match the ones from the client certificate, a Forbidden response is returned.

ASWellKnownFilter

This filter updates the AS well-known configuration returned by Identity Cloud or AM.

  • Filter source: ASWellKnownFilter.groovy
  • Process type: RESPONSE
  • Filter processing:
    • Modifies the well-known response to restrict the supported auth methods to the ones defined in the tokenEndpointAuthMethodsSupported filter arg.
    • Modifies the well-known response to replace the IG hostname with the MTLS hostname for the endpoints defined in the mtlsEndpoints arg.

AuditConsent

This filter prepares the consent audit trail in JSON format.

VerifyAccessTokenScopes

This filter ensures that the access token required for accessing the API must have at last one scope of configured 'allowedScopes'

  • Filter source: VerifyAccessTokenScopes.groovy
  • Process type: REQUEST
  • Filter Processing:
    • Requires the filter OAuth2ResourceServerFilter to inject the access token in the OAuth2Context before validate the scopes
    • Get the access_token info from the OAuth2Context and validates the scopes against the allowed scopes configured

CreateApiClient

This filter registers the TPP organisation and OAuth 2.0 client in Identity Cloud or IDM.

  • Filter source: CreateApiClient.groovy
  • Process type: REQUEST
  • Filter processing:
    • Reads the OIDC dynamic registration response and creates the apiClientOrg managed object in Identity Cloud or IDM.
      • If there isn't any registration data in the response, a Bad Request response is returned.

Grant Type Verifier

The filter verifies that the current access token's grant type is allowed in the allowedGrantType field.

  • Filter source: GrantTypeVerifier.groovy
  • Process type: REQUEST
  • Filter processing:
    • If the grant type value is validated, continue the filter chain.
    • If the grant type does not correspond to the configured one, a 401 Unauthorized error is returned and the filter chain is interrupted.

JwkmsBuildSSA

This filter creates the SSA payload.

  • Filter source: JwkmsBuildSSA.groovy
  • Process type: REQUEST
  • Filter processing:
    • Checks that the client certificate contains all the required details.
      • If the certificate itself is missing, or does not contain a CN or org identifier, a Bad Request response is returned.
      • If the org identifier is the wrong length, a Forbidden response is returned.
    • Builds the SSA payload.

JWKSProxyProcessRequest

This filter checks the jwks_uri against a list of authorised JWKS hosts.

  • Filter source: JWKSProxyProcessRequest.groovy
  • Process type: REQUEST
  • Filter processing:
    • If the proxy URL is badly formatted, a Bad Request response is returned.
    • If the authorised JWKS hosts list is missing or cannot be parsed, an Internal Server Error is returned.
    • If one of the authorised hosts is not permitted, a Forbidden response is returned.

ObResponseCheck

This filter checks for an Open Banking compliant header and adds one if it's missing, and also ensures the response is compliant.

  • Filter source: ObResponseCheck.groovy
  • Process type: RESPONSE
  • Filter processing:
    • Ensures that the response has a FAPI interaction ID header. If the response doesn't already contain the x-fapi-interaction-id header, then the filter will generate a random one.
    • Verifies the response status. If the status is in the client or server error response families and the error is not compliant with the Open Banking Specifications, the response body is modified accordingly.

ParseCertificate

This filter retrieves the certificate from the header, processes it and saves it to the clientCertificate object.

  • Filter source: ParseCertificate.groovy
  • Process type: REQUEST
  • Filter processing:
    • Retrieves a certificate from the configured header on the parameter routeArgCertificateHeader.
      • If the header is not found, an error response is returned.
      • If the header is found, the value is URL decoded and then initialised as an X.509 certificate. The resulting object is saved to the attributes context under the clientCertificate object.

ProcessDetachedSig

This filter checks the incoming detached signature and saves it to the route state. If the detached signature is for an unencoded payload, validation is also performed.

  • Filter source: ProcessDetachedSig.groovy
  • Process type: REQUEST
  • Filter processing:
    • The filter only applies if the request method is POST.
    • Parses API version from the inbound request.
      • If the API version cannot be parsed from the inbound request, a Bad Request response is returned.
    • Builds the JWT from the detached header.
      • If the detached signature header is missing from the inbound request or the detached signature has the wrong number of dots, a Bad Request response is returned.
    • Retrieves the JWS header and checks it for the b64 claim:
      • If the b64 claim exists and is set to false, and the API version is 3.1.3 or lower, then it is accepted and the detached signature is validated as a non-base64 payload.
      • If the b64 claim exists and the API version is 3.1.4 or higher, then it is rejected.
      • If the b64 claim does not exist and the API version is 3.1.4 or higher, then it is accepted and the detached signature is validated as a standard base64 payload.

ProcessRegistration

This filter verifies the registration request and prepares the Identity Cloud or AM dynamic client registration JSON.

  • Filter source: ProcessRegistration.groovy
  • Process type: REQUEST
  • Filter processing:
    • Checks that all the needed details are available in the client certificate for registration.
      • If the client certificate is missing or doesn't contain roles, a Bad Request response is returned.
    • Parses the incoming registration JWT and extracts the SSA.
      • If the registration has expired, it contains unsupported response types, there is no SSA or the issuer claim is invalid, a Bad Request response is returned.
    • Updates the OIDC registration request.
      • If the JWKS URI host is in the list of private JWKS hosts, then the request is proxied back through IG.
        • If the proxied JWKS host cannot be parsed, an Internal Server Error is returned.
        • If the JWKS URI is invalid, a Bad Request response is returned.
      • If the JWKS URI host is not in the list of private JWKS hosts, then a Bad Request response is returned because it must contain a valid JWKS endpoint.
    • The SSA and registration JWT is then stored for signature checks.

RcsApiConsentRequestJwtResolver

This filter resolves the location of the consent request JWT for calls to the RCS Backend (API).

  • Filter source: RcsApiConsentRequestJwtResolver.groovy
  • Process type: REQUEST
  • Filter processing:
    • For calls to the /details endpoint (which populates the UI), the JWT is included in the POST body as a raw string.
    • For calls to the /decision endpoint (which submits the consent decision), the JWT is included in the consentJwt field of a JSON object in the POST body.

RequestEntityConsentIdValidator

This filter checks the consent submitted matches the consent from the access token.

RequestPathConsentIdValidator

This filter checks the consentId in the URI path matches the access token.

SaveIntentIdOnAttributesContext

This filter gets the intent ID from the access token claims found on the OAuth2 context and saves it on the attributes context.

ScriptableHandlers

JwkmsGetTlsCert

This handler converts the incoming JWK set to PEM encoded TLS client certificate and key.

  • Handler source: JwkmsGetTlsCert.groovy
  • Process type: REQUEST
  • Handler processing:
    • If the request body cannot be parsed as a JWK set, the TLS key cannot be found in the JWK set, or the private key and/or certificate chain cannot be found in the TLS JWK, a Bad Request response is returned.

JwkmsIssueCert

This handler generates certificates and keys, and returns them as a JWK set.

JwkmsSignClientClaims

This handler signs claims using the signing key from the incoming JWK set.

RepoApiClient

This handler fetches OAuth 2.0 client details from Identity Cloud or IDM.

  • Handler source: RepoApiClient.groovy
  • Process type: REQUEST
  • Handler processing:
    • If the client ID cannot be parsed from the inbound request, a Bad Request response is returned.

RepoUser

This handler fetches user information from Identity Cloud or IDM.

  • Handler source: RepoUser.groovy
  • Process type: REQUEST
  • Handler processing:
    • If the API client ID cannot be parsed from the inbound request, a Bad Request response is returned.

SetContentTypeToPlainText

This handler sets the content type for the JWT to text/plain.

Clone this wiki locally