APIs

Brasil Non Standard SSA API

For the Open Finance Brasil ecosystem, Raidiam Connect has a non standard Software Statement Assertion API to reflect the ecosystem needs.
﻿
Loading...
Loading...
﻿
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 software_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.
Text
{
"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": "[email protected]",
    "phone": "+447890130558",
    "type": "business"
  },
  {
    "name": "contact name",
    "email": "[email protected]",
    "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
}
{
"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 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.

Metadata	Description	Source Specification
softwareid	Unique Identifier for Client Software	[RFC7591]
iss	SSA Issuer	[RFC7519]
iat	Time SSA issued	[RFC7519]
jti	JWT ID	[RFC7519]

Metadata	Description	Field Size
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

Metadata	Description	Field Size
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

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.

Standard SSA API