Standard SSA API

terminology this specification uses the terms "access token", "authorization code", "authorization endpoint", "authorization grant", "authorization server", "client", "client identifier", "client secret", "grant type", "protected resource", "redirection uri", "refresh token", "resource owner", "resource server", "response type", and "token endpoint" defined by oauth 2 0 \[rfc6749] and uses the term "claim" defined by json web token (jwt) \[rfc7519] organisation an organisation managing customer accounts (and operating banking apis) primary technical contact the person at the org who creates an ssa and invokes a registration mechanism this is an example of an \[rfc7591] client developer organisation id the unique identifier for each directory participant role an implementation of an authority; acts as an identity provider, certificate authority, and registry governing the participants in the uk api scheme registration endpoint oauth 2 0 & \[rfc7591] compliant endpoint software statement assertion (ssa) an implementation of an \[rfc7591] software statement, signed by the directory trusted third party an organization working to initiate payments or consume account information client software software implementing an oauth2 client, interacting with an org's registration endpoint software statement assertion (ssa) the ssa is a json web token (jwt) containing client metadata about an instance of client software the jwt is issued and signed by the directory ssa payload the payload of the ssa must be a compliant software statement according to \[rfc7591] the ssa must also be a compliant jwt according to \[rfc7519] the following metadata profiles the metadata in \[rfc7591] and \[rfc7519] metadata description source specification softwareid unique identifier for client software \[rfc7591] iss ssa issuer \[rfc7519] iat time ssa issued \[rfc7519] jti jwt id \[rfc7519] the following software metadata is additionally defined for this profile metadata description field size default values softwareclientid the client id registered in directory services used to access directory resources base62 guid (22 chars) softwareclientdescription human readable detailed description of the client max256text softwareclientname human readable software statement name max40text softwareclienturi the website or resource root uri max256text softwareversion the version number of the software should an org choose to register and / or maintain it decimal softwareenvironment requested additional field to avoid certificate check max256text softwarejwksuri contains all active signing and network certs for the software max256text softwarejwksrevokeduri contains all revoked signing and network certs for the software max256text softwarelogouri link to the org logo max256text softwaremode org requested additional field to indicate that this software is test or live the default is live impact and support for test software is up to the org max40text softwareonbehalfof a reference to fourth party organisation resource on the directory if the registering app is acting on behalf of another max40text softwarepolicyuri a link to the software's policy page max256text softwareredirecturis registered client callback endpoints as registered with rts a string array of max256text items softwareauthorityclaims a multi value list of roles that this software is authorized to perform a string array of authority claims items softwaretosuri a link to the software's terms of service page max256text the following organisational metadata is defined for this profile metadata description field size default values organisationauthorityclaims claims object for the organisation detailing all the authorisation roles orgstatus included to cater for voluntary withdrawal from directory scenarios active , revoked , or withdrawn orgid the unique organisation id max35text orgname legal entity identifier or other known organisation name max140text orgcontacts json array of objects containing a triplet of name, email, and phone number each item max256text orgjwksuri contains all active signing and network certs for the organisation max256text orgjwksrevokeduri contains all revoked signing and network certs for the organisation max256text ssa header the ssa header must comply with \[rfc7519] metadata description comments typ must be set to jwt alg must be set to es256 or ps256 note the majority of ecosystems use rsa keys so support for ps256 is critical kid the kid will be kept the same as the x5t parameter (x 509 certificate sha 1 thumbprint) of the signing certificate federation/non federation the ssa api is designed to support both federated and non federated trust frameworks when oidc federation is not utilized within the trust framework, the client uri parameter is excluded from the softwarestatementassertionbody example ssa the elements defined in the software statement will consist of the following values note that there are inconsistent applications of booleans or "active" strings in the current data model note that there are inconsistent applications of status flags case sensitivity the attributes required to be displayed by orgs { "typ" "jwt", "alg" "es256", "kid" "abcd1234" } { "iss" "example ltd", "iat" 1492756331, "jti" "id12345685439487678", "softwareenvironment" "production", "softwaremode" "live", "softwareid" "65d1f27c 4aea 4549 9c21 60e495a7a86f", "softwareclientid" "xclient unique id", "softwareclientname" "amazon prime movies", "softwareclientdescription" "amazon prime movies is a moving streaming service", "softwareversion" "2 2", "softwareclienturi" "https //prime amazon com", "softwareredirecturis" \[ "https //prime amazon com/cb", "https //prime amazon co uk/cb" ], "softwareauthorityclaims" { "authorisationdomains" \[ { "authorisationdomain" "pds2", "roles" \[ { "role" "aspsp", "status" "active" } ] }, { "authorisationdomain" "pensions", "roles" \[ { "role" "tpp", "status" "active" }, { "role" "aspsp", "status" "active" } ] } ] }, "organisationauthorityclaims" \[ { "authorityid" "123", "registrationid" "111111", "authorisationdomains" \[ { "authorisationdomain" "pds2", "roles" \[ { "role" "aspsp", "authorisations" \[ { "status" "active", "memberstate" "gb" }, { "status" "active", "memberstate" "il" } ] }, { "role" "aisp", "authorisations" \[ { "status" "active", "memberstate" "gb" }, { "status" "active", "memberstate" "il" } ] } ] }, { "authorisationdomain" "pensions", "roles" \[ { "role" "aspsp", "authorisations" \[ { "status" "active", "memberstate" "gb" }, { "status" "active", "memberstate" "il" } ] }, { "role" "tpp", "authorisations" \[ { "status" "active", "memberstate" "gb" }, { "status" "active", "memberstate" "il" } ] } ] } ] } ], "softwarelogouri" "https //mycompanyprofile com/logo png", "orgstatus" "active", "orgid" "my company's id", "orgname" "registered name", "orgcontacts" \[ { "name" "contact name", "email" "contact\@contact com", "phone" "+447890130558", "type" "business" }, { "name" "contact name", "email" "contact\@contact com", "phone" "+447890130558", "type" "technical" } ], "orgjwksuri" "https //jwks raidiam ts uk/org id/org id jkws", "orgjwksrevokeduri" "https //jwks raidiam ts uk/org id/revoked/org id jkws", "softwarejwksuri" "https //jwks raidiam ts uk/org id/software id jkws", "softwarejwksrevokeduri" "https //jwks raidiam ts uk/org id/revoked/software id jkws", "softwarepolicyuri" "https //myapp com/policy html", "softwaretosuri" "https //myapp com/tos html", "softwareonbehalfof" "a mediator ltd" } { signature } automated client registration an organisation may use automated client registration to submit an ssa in exchange for client credentials for use as a client against an oauth 2 0 authorization server it is recommended for orgs to support the automated client registration mechanism a large number of claims that openid connect ops could support as part of the rfc7591 request are detailed https //openid net/specs/openid connect registration 1 0 html#clientmetadata https //openid net/specs/openid connect registration 1 0 html#clientmetadata and should be followed if not explicitly referenced in the software statement assertion claim set request validation prior to issuing a client registration response, the orgs must perform the following checks the org should check whether the initiated tls connection is the same org as listed in the ssa in the case where a gateway or other piece of infrastructure pre terminates the matls channel in front of the registration endpoint, the certificate used to initiate the connection or some part of that certificate (such as dn & issuer) should be made available to the org for validation against the claims in the ssa the registration request must be signed with a key contained in the jwks referenced in the ssa included with the request this ensures that a holder of key proof of possession is performed proving that the app was the originally intended recipient of the ssa when the directory services issued it the ssa must be validated according to \[rfc7519], including validation of the signature and validity window jwt signature must be validated, this involves retrieving the jwks keyset for both the directory and the app the keystore location will be published as part of the directory specification, the app's will be included in the software statement ssa lifetime the ssa's lifetime / validity period is not defined by rts orgs in the directory ecosystem are required to implement pragmatic time ranges in which to accept an ssa for example, an org that has implemented dynamic client registration may choose to accept ssa's that were issued no earlier than 1 minute prior to their presentation however orgs that only support manual registration may need to accept ssas that were issued 30 minutes prior as the elapsed time period between generation and use between these two flows is expected to differ significantly