Package org.forgerock.openig.fapi.dcr.trusteddirectory

Class TrustedDirectory

java.lang.Object
org.forgerock.openig.fapi.dcr.trusteddirectory.TrustedDirectory
public final class TrustedDirectory extends Object
A Trusted Directory is a trust anchor that acts as the central point of trust for a particular ecosystem, such as Open Banking UK. It is trusted by both the ApiClients and the systems providing the APIs.

It is responsible for issuing the OAuth2.0 software statements of the clients and API providers in the ecosystem, and the certificates associated with those statements.

The directory MUST host a JWKS endpoint containing its public keys, which were used to sign the software statements it issues.

The directory MAY host JWKS endpoints for the certificates associated with the software statements. Alternatively, it may embed the JWKS in the software statement. These JWKSs are used to validate JWT signatures produced by the ApiClient.

The Trusted Directory contains a SoftwareStatementMapper that handles mapping the structure of the software statements issued by the directory on to SoftwareStatement objects. Method decodeSoftwareStatementAssertion(org.forgerock.json.jose.jws.SignedJwt) uses the mapper to decode a software statement assertion JWT issued by this directory. 

 {
      "type": "TrustedDirectory",
      "config": {
         "issuer"                  : String                  [REQUIRED - The issuer name of the Trusted Directory.
                                                                         Must match the 'iss' claim in the software
                                                                         statement assertions JWTs issued by this
                                                                         directory. ]
         "softwareStatementClaims" : object                  [REQUIRED - The claim names used in the software
                                                                         statements issued by this directory.]
         {
           "organisationIdClaimName"  : Config Expression<String>  [REQUIRED]
           "organisationNameClaimName": Config Expression<String>  [REQUIRED]
           "softwareIdClaimName"      : Config Expression<String>  [REQUIRED]
           "clientNameClaimName"      : Config Expression<String>  [REQUIRED]
           "redirectUrisClaimName"    : Config Expression<String>  [REQUIRED]
           "rolesClaimName"           : Config Expression<String>  [OPTIONAL - if not provided, roles will not be
                                                                               extracted]
           "jwksUriClaimName"         : Config Expression<String>  [OPTIONAL - if not provided, jwksClaimName must
                                                                               be provided]
           "jwksClaimName"            : Config Expression<String>  [OPTIONAL - if not provided, jwksUriClaimName
                                                                               must be provided]
         },
         "secretsProvider"         : SecretsProvider         [REQUIRED - The SecretsProvider containing the public
                                                                         keys of this directory, to enable software
                                                                         statement assertion JWTs to be verified.
                                                                         Typically, this will be a SecretsProvider
                                                                         containing a JwkSetSecretStore.]
         "verificationSecretId" : Config Expression<Verification Secret ID> [OPTIONAL - verification secret ID of the
                                                                                        key to use to validate the
                                                                                        signature software statement
                                                                                        assertion JWTs. Defaults to
                                                                                        "verify"]
      }
 }

The example configuration below shows how to configure a trusted directory for the Open Banking UK test environment. 

 {
     "name" : "OpenBankingTestDirectory",
     "type" : "TrustedDirectory",
     "config" : {
       "issuer" : "OpenBanking Ltd",
       "softwareStatementClaims" : {
          "organisationIdClaimName": "org_id",
          "organisationNameClaimName": "org_name",
          "softwareIdClaimName": "software_id",
          "clientNameClaimName": "software_client_name",
          "redirectUrisClaimName": "software_redirect_uris",
          "softwareRolesClaimName": "software_roles",
          "jwksUriClaimName": "software_jwks_endpoint"
       },
       "secretsProvider": {
         "type": "SecretsProvider",
         "config": {
           "stores": [{
             "type": "JwkSetSecretStore",
             "config": {
               "jwkUrl": "https://keystore.openbankingtest.org.uk/keystore/openbanking.jwks",
               "handler": "OBDirectoryClientHandler"
             }
           }]
         }
       }
     }
 }
For Trusted Directories that host a JWKS endpoint, the SecretsProvider configuration will contain a JwkSetSecretStore that uses the JWKS endpoint. The JwkSetSecretStore handler must be able to communicate with the jwkUrl endpoint of the directory. In the above example, the Open Banking directory uses self-signed certificates and therefore requires a handler configured to trust these certificates. See HttpClientHandlerHeaplet and ClientTlsOptionsHeaplet for handler configuration details.