Version: 1.20.7

Raidiam Connect SSA APIs

Raidiam Connect Standard Software Statement Assertion APIs

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
`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
`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 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.

Contact

support@raidiam.com

License

MIT

Get Software Statement Assertion for Given SoftwareStatementID

Fetch a signed JSON Web Token containing a Software Statement Assertion.

Raidiam Connect SSA APIs

Software Statement Assertion (SSA)​

SSA Payload​

SSA Header​

Federation/Non Federation​

Example SSA​

Automated Client Registration​

Request Validation​

SSA Lifetime​