Open Banking update to the software statement verifier for dynamic OAuth client registration
Open Banking clients can use dynamic registration with providers, a style of OAuth 2.0 client registration based on RFC 7591 that is API-based and lets itself to be fully automated.
To prove its belonging to a regulated Open Banking entity the client includes a software statement assertion (SSA) in the client registration request. The SSA is a signed JSON Web Token (JWT) issued by the Open Banking directory and contains important details such the organisation's identity and keys endpoint URL.
Example client registration request with an embedded software statement as JWT (note, in Open Banking the registration JSON is additionally secured with a JWS and sent with a client X.509 certificate for a mutually authenticated HTTPS):
POST /clients HTTP/1.1
Content-Type: application/json
Host: c2id.com
{
"redirect_uris" : [ "https://client.example.org/callback" ],
"token_endpoint_auth_method" : "private_key_jwt",
"token_endpoint_auth_signing_alg" : "PS256",
"scope" : "openid account",
"software_statement" : "eyJhbGciOiJSUzI1NiJ9xaemaep4waibohphsf09..."
}
To handle special client registration profiles such as in Open Banking the Connect2id server comes with a plugin interface for intercepting client registration requests. To make the job of integrators even easier we maintain an open source plugin which can be configured to perform all necessary validations for the Open Banking SSA as well as the additional top-level JWS of the client registration request and its mutual TLS authentication.
One question that often comes up in dynamic client registration is how to control the optional scope metadata field that may be used to bound the scope values that the client may request?
The default policy of the plugin is to scrub the scope field if it's set by the client because allowing the client to set the scope bounds on its own access tokens can compromise the security of the OAuth 2.0 server.
The decision what scope values to allow for a client can however be based on the embedded SSA because it carries a proof of the client's identity, such as the legal entity behind it, its software roles and other useful details from the Open Banking directory.
Sample Open Banking SSA claims snippet:
{
"iss" : "OpenBanking Ltd",
"iat" : 1614268968,
"jti" : "seesh6IeFemahboi",
"software_redirect_uris" : [ "https://client.example.com/cb" ],
"software_roles" : [ "AISP", "PISP", "CBPII" ],
"org_status" : "Active",
"org_name" : "XYZ Bank",
"org_jwks_endpoint" : "https://keystore.openbanking...",
"org_jwks_revoked_endpoint" : "https://keystore.openbanking...",
"software_jwks_endpoint" : "https://keystore.openbanking...",
"software_jwks_revoked_endpoint" : "https://keystore.openbanking..."
}
In release 2.2 of the SSA plugin we added the ability to configure scope rules based on claims in the software statement.
Each scope rule is represented by JSON Path expressions: if the JSON Path query produces a match in the software statement JSON then the configured scope values for the rule are allowed to pass.
The use of JSON Path gives Open Banking deployments of the Connect2id server plenty of flexibility to define scope policies based on the SSA.
Example rules for allowing clients with the AISP role to register for the
scope openid accounts and those with the PISP role for the scope openid
payments:
op.ssv.scopeRules.1.scope=openid accounts
op.ssv.scopeRules.1.jsonPath=$.software_roles[?(@=='AISP')]
op.ssv.scopeRules.2.scope=openid payments
op.ssv.scopeRules.2.jsonPath=$.software_roles[?(@=='PISP')]
You can do quick online JSON Path tests with the tool at jsonpath.com.
The SSA plugin can be further configured to shape the client registration request after the statement has been merged, by moving, renaming or deleting selected fields to produce a final request that matches the OAuth 2.0 server's registration policies and idioms.
The SSA plugin is compatible with Connect2id server releases 11+ and the most recent v2.2 of it will be include in the next 11.3 release.