Standard SSA API
Loading...
Loading...
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.
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.
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 |  |
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. |  |
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.
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.
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 and should be followed if not explicitly referenced in the Software Statement Assertion claim set.
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.
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.