...
| Awesome api app render macro | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
openapi: 3.0.1
servers:
- url: https://<your-ozone-hh-server>
info:
title: Headless Heimdall APIs
contact:
name: Ozone Financial Technology Limited
description: |
This document provides an API description in [OpenAPI](https://spec.openapis.org/oas/v3.0.1.html)
for the Headless Heimdall APIs.
This document provides the OpenAPI description for the APIs provided by Headless Heimdall.
These APIs are implemented by Ozone and should be called by the financial institution at the end of their authorization journeys.
The interface allows an financial institution to develop the user interface for customers without
having to deal with the complexities of OpenID Connect (OIDC) and the FAPI 2.0 Security Profile and without having to gain a
thorough understanding of the constraints placed by FAPI.
The interface consists of three operations, which are called when User authentication is initiated and after it is completed.
> Please note that where an operation name is used it references the `operationId` value for a given endpoint and HTTP method
Initiating Authorization is supported by the `getAuth` operation:
- The `getAuth` operation (`get /auth`) should be called by the financial institution
at the institution at the beginning of an authorization code grant. This is typically
immediately after it receives an authorization
request from a TPP.
Completing Authorization is supported by the `doConfirm` and `doFail` operations:
- The `doConfirm` operation (`post /auth/{interactionId}/doConfirm`) should be
called by the financial institution to notify Heimdall that an interaction has
completed successfully.
- The `doFail` operation (`post /auth/{interactionId}/doFail`) operation should be
called by the financial institution to notify Heimdall that the interaction has
failed.
### #### ChangesChanges in Version 2024.3746.0
* RefactoredAdded `post`additional operationsproperties to usethe a`tpp` Pathdata parameterprovided in the `get /auth` response
*
Refined descriptions to add clarity* forAdded readersdetails on content of `decodedSsa` property *to Removed `additionalProperties: true` as not required and causes tooling issues
provide guidance on
properties like `logo_uri` and `jwks_uri`
#### Changes#### Changes in Version 2024.3437.10
* Refactored Security`post` Schemeoperations Objects to use a commonPath definitionsparameter
across
all API Hub APIs * Refined descriptions to add *clarity Implementedfor thereaders
correct
Security Requirements for this API* description,Removed reflecting`additionalProperties: securitytrue` patternsas availablenot inrequired APIand Hubcauses tooling issues
version: 2024.37.0 tags: * Added - name: Initiate`login_hint` to Authorization Request parameters
description: Operations that support#### initiatingChanges thein authorization of a UserVersion 2024.34.1
- name:* CompleteRefactored AuthorizationSecurity Scheme Objects to use description:common Operationsdefinitions thatacross supportall completingAPI theHub authorization
of a User, APIs
indicating either success or* failureImplemented the security:correct Security Requirements -for {}this API description, -
OzoneConnectJwtAuth: [] paths: /auth:
get:reflecting security patterns available in API Hub
version: 2024.46.0
tags:
- - name: Initiate Authorization
description: Operations summary:that Initiatesupport aninitiating authorisationthe interactionauthorization of a User
- operationIdname: getAuthComplete Authorization
description: |Operations that support completing the authorization of a User,
The `getAuth` operation should be called byindicating theeither financialsuccess institutionor atfailure
the
beginningsecurity:
of the - {}
- OzoneConnectJwtAuth: []
interaction.paths:
The operation validates/auth:
all the parameters that areget:
passed to it to ensure that thetags:
authorization- requestInitiate isAuthorization
FAPI compliant and has only the client_id` and `redirect_uri` parameters.
summary: Initiate an authorisation interaction
The operation responds with one of the three outcomes:
operationId: getAuth
description: |
- __Success__: TheThe `getAuth` operation returnsshould abe statuscalled 200.by Thethe bodyfinancial containsinstitution aat JSONthe objectbeginning withof the
interaction. The operation andvalidates all the query parameters extractedthat fromare thepassed OIDCto requestit object.to ensure that the
- __Non-redirectable failure__: This indicates a failure where validation of the OIDC Client authorization request is FAPI compliant and has only the client_id` and `redirect_uri` parameters.
failed. The operation financialresponds institutionwith shouldone renderof anthe errorthree pageoutcomes:
and
end the interaction.
- __Redirectable failureSuccess__: The Thisoperation indicatesreturns a status failure200. whereThe thebody OIDCcontains clienta hasJSON beenobject validatedwith the
butinteraction validationand ofall the query parameters ofextracted from the AuthorizationOIDC Requestrequest failedobject.
The
operation therefore - __Non-redirectable failure__: respondsThis withindicates a 303 redirect, whichfailure where validation of the OIDC financialClient
institution must use to redirect the User **without modification** failed. The financial institution should render an error page and ###end Processingthe ainteraction.
success
response - There are two properties in the success response that financial institutions are likely to be interested in:
- `interaction.interactionId`: The interaction identifier that should be used with__Redirectable failure__: This indicates a failure where the OIDC client has been validated
but validation of the parameters of the Authorization Request failed. The operation therefore
responds with a 303 subsequentredirect, callswhich tothe Headlessfinancial Heimdallinstitution whenmust thisuse authorizationto requestredirect isthe completedUser by the financial institution.**without modification**.
### Processing - `tpp.directoryRecord`: Where Ozone is integrated with a Directory Service, this contains a record
of the TPP record as held on the directory. The structure of the record will depend on the directory. Directory record as held by Ozone in base 64 encoded format.a success response
There are two properties in the success response that financial institutions are likely to be interested in:
- `interaction.interactionId`: The interaction identifier that should be used with
subsequent calls to Headless ###Heimdall Parameterswhen this authorization request is completed by the financial institution.
When calling this API, the financial institution must pass on **all the query parameters or hash parameters** received from the TPP- `tpp.directoryRecord`: Where Ozone is integrated with a Directory Service, this contains a record
inof the authorizationTPP request.record The FAPI 2.0 Security Profile states that a Client will **_only_** send the `client_id` and `request_uri` values, asas held on the directory. The structure of the record will depend on the directory. Directory record as held by Ozone in base 64 encoded format.
### Parameters
When calling specifiedthis byAPI, the [Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#section-5. financial institution must pass on **all the query parameters or hash parameters** received from the TPP
in the authorization request. The FAPI 2.0 Security Profile states that a Client will **_only_** send the `client_id` and `request_uri` values, as
specified by the [Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#section-5.3.3.2-2.6). However, Heimdall is
the authoritative source for making that decision, hence all query parameters must be passed on. No query parameters are therefore
defined here as a result.
responses:
"200":
description: |
However, Heimdall is
the authoritative source for making that decision, hence all query parameters must be passed on. No query parameters are therefore
defined here as a result.
responses:
"200":
description: |
This indicates that the parameters were successfully validated.
The financial institution should continue with the next stages of the interaction, using the `interactionId`
as the unique identifier with which to track the interaction with the User
content:
application/json:
schema:
$ref: '#/components/schemas/AuthSuccessResponse'
"303":
description: |
This indicates that the parameters were not successfully verified.
However, there were no indications that the request originated from an invalid client.
The financial institution should respond to the customer with a redirect to the URI returned by the API
(including the query or hash parameters included in the URL)
"400":
description: |
This indicates that the parameters were not successfully verified.
Heimdall could not verify that the request originated from a valid client.
The financial institution should render an error page and __must not__ redirect back to the TPP.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthErrorResponse'
/auth/{interactionId}/doConfirm:
post:
operationId: doConfirm
tags:
- Complete Authorization
summary: End an authorisation interaction with a success response
description: |
The `doConfirm` operation should be called by the financial institution once the
user interaction has been completed and the resource owner has authorized
access. This operation updates the interaction state and generates an OIDC
Authorization Code value - `code` - and the rest of the response that should be
returned to the TPP.
When supported by Security Profile the financial institution can specify the
set of claims to be added to the ID Token. Heimdall creates an ID Token with
these claims along with any claims required by FAPI and OIDC. Please note that
under the FAPI 2.0 Security Profile ID Tokens are not supported in the front
channel, and therefore will not be returned to the Client as the result of an
interaction. Please refer to the [Security Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#table-1)
for more details.
Heimdall returns a 303 with a redirect uri. This resource owner should be
redirected to this URI.
### Parameters
The request body can contain an arbitrary set of
`application/x-www-form-urlencoded` name-value pairs. These are added by
Heimdall to the ID Token. The claim name is set to the parameter name and the
claim value to the parameter value.
Claim names prefixed by `heimdall.` act as control parameters for the tokens
that are produced. These claims are not added to the ID Token.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
description: Where supported, allows a financial institution to send parameters
that control the lifetime of Access Tokens and availability of
Refresh Tokens. These features are not supported for the UAE
Open Finance Framework. Financial institutions can, however, add claims that will
be included in an ID Token, which can be requested by a TPP dependent on the OAuth
scope granted by the User.
type: object
parameters:
- $ref: '#/components/parameters/InteractionId'
responses:
"303":
description: |
A redirect URI that contains an authorization code along with additional
parameters as required by OIDC.
If an internal error occurs during processing of the request an `error` and
`error_description` parameters will be returned.
The redirect URI must be returned to the User to redirect them back to the TPP.
/auth/{interactionId}/doFail:
post:
operationId: doFail
tags:
- Complete Authorization
summary: End an authorisation interaction with a failure response
description: |
The `doFail` operation should be called by the financial institution once the
User interaction has been completed and has resulted in a failure to grant
access to the TPP. Examples failure scenarios include:
* The User does not authenticate successfully.
* The User declines the authorisation of consent.
The `doFail` operation updates the interaction state, generates an OIDC `error`
and returns Thisthe indicatesrest thatof the parametersresponse werethat successfullyshould validated.be returned to the TPP.
The financial institution shouldcan continue withspecify the next`error` stagesand of the interaction, using the `interactionId``error_description` as
x-www-form-urlencoded parameters. If `error` and as`error_description` theomitted unique
identifier with which to track the interaction with thethen Userdefault values will be returned in the redirect URI.
content:
Heimdall returns a 303 application/json:with a redirect URI, which should be sent to the
schema: User to redirect them to the TPP.
$refrequestBody:
'#/components/schemas/AuthSuccessResponse' "303"content:
descriptionapplication/x-www-form-urlencoded:
| schema:
This indicates that the parameters were not successfully verified. type: object
However, there were no indications that the requestproperties:
originated from an invalid client. error:
The financial institution should respond to the customer with a redirect to the URI returned by the APItype: string
(including the query or hash parameters included indescription: the|
URL) "400": An description: |
OAuth2.0 or OIDC error
This indicates that the parameters were not successfully verified.error_description:
Heimdall could not verify thattype: thestring
request
originated from a valid client. parameters:
- $ref: The financial institution should render an error page and __must not__ redirect back to the TPP.
'#/components/parameters/InteractionId'
responses:
"303":
contentdescription: |
application/json: A redirect URI that contains the parameters required to indicate the error to
schema: the TPP.
$ref: '#/components/schemas/AuthErrorResponse' /auth/{interactionId}/doConfirm:
post: operationId: doConfirm If an internal error occurs tags:during processing of the request an `error` and
- Complete Authorization summary: End an authorisation`error_description` interactionparameters withwill abe successreturned.
response description: |
The `doConfirm` operation should be called by theThe financialredirect institutionURI oncemust thebe returned to the User to redirect them back to userthe interactionTPP.
hascomponents:
been completed andschemas:
the resource owner has authorizedInteractionId:
description: Unique identifier access.for Thisthe operationinteraction updateswith the interactionUser
state and generates an OIDC type: string
AuthSuccessResponse:
Authorization Code value - `code`type: -object
and the rest of the response thatproperties:
should be interaction:
returned to the TPP. description: The properties of a Whensuccessfully supportedinitiated byinteraction
Security Profile the financial institution can specify the type: object
set of claims to be added toproperties:
the ID Token. Heimdall creates an ID Token with interactionId:
these claims along with any claims required by FAPI and OIDC. Please note that$ref: '#/components/schemas/InteractionId'
underparams:
the FAPI 2.0 Security Profile ID Tokens are not supported in the front description: Query parameters unbundled from the original authorization channelrequest, andincluding therefore
will not be returned to the Client as the result of an query parameters, hash interaction.parameters, Pleaseand referproperties to the [Security Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#table-1)of the JWT-Secured
for more details. Authorization Request (JAR) Heimdallsent returnsin athe 303Pushed withAuthorization aRequest.
redirect uri. This resource owner should be type: object
redirected to this URI. ### Parametersproperties:
The request body can contain an arbitrary setclient_id:
of `application/x-www-form-urlencoded` name-value pairs. These are added by description: The `client_id` value that the caller Heimdallclaims to have. At thethis IDstage,
Token. The claim name is set to the parameter name and the Heimdall claimhas valueverified tothat the parameter`client_id` valueexists.
Claim names prefixed by `heimdall.` act as control parameters fortype: thestring
tokens that are produced. These claims are not added to the ID Token. response_type:
requestBody: contentdescription: The request grant type. This will default to `code` application/x-www-form-urlencoded:
for the CBUAE release
schema: as per the constraints description:of Wherethe supported, allows a financial institution to send parametersFAPI 2.0 Security Profile
type: string
that control the lifetime of Access Tokens and availability of enum:
Refresh Tokens. These features are not supported for the UAE - code
Open Finance Framework. Financial institutions can,scope:
however, add claims that will type: string
be included in an ID Token, which can be requested by a TPP dependent on therequest:
OAuth scope grantedtype: bystring
the User. typescopes:
object parameters: - $refdescription: '#/components/parameters/InteractionId'
responses:The requested scopes in the Authorization Request
"303": descriptiontype: |array
A redirect URI that contains an authorizationitems:
code along with additional parameters as required bytype: OIDC.string
If an internal errorclaims:
occurs during processing of the request an `error` and description: The requested `error_description` parameters will be returned.claims in the Authorization Request.
type: object
The redirect URI must be returned to the User tologin_hint:
redirect them back to the TPP. /auth/{interactionId}/doFail: post: description: The value operationId:of doFailthe `login_hint` parameter sent in the Pushed tags:Authorization
- Complete Authorization summary: End an authorisation interactionrequest. withThis avalue failureis responseexpected to be encrypted as a JWE.
description: | The `doFail` operation should be called by thetype: financialstring
institution once the Userclaims:
interaction has been completed and has resulted in a failure to grant type: object
access to the TPP. Examples failure scenarios includestatus:
* The User does nottype: authenticatestring
successfully. * The UserconsentId:
declines the authorisation of consent. Thetype: `doFail`string
operation updates the interaction state, generates an OIDC `error` description: An identifier for andconsent
returns the rest of the response that should be returned to the TPP. deprecated: true
The financial institution can specify the `error`consentIdsList:
and `error_description` as x-www-form-urlencoded parameters. Iftype: `error`array
and `error_description` omitted then default valuesdescription: will|
be returned in the redirect URI. Heimdall returnsConsent aIds 303associated with the ainteraction.
redirect URI, which should be sent to the Note Userthat toRAR redirectrequests themmay tocontain themultiple TPPconsents. However, support for this is not required requestBody:in the CBUAE 2024 standards and LFIs may consider
content: application/x-www-form-urlencoded: that this array may have a single value.
schema: items:
type: object propertiestype: string
tpp:
error: $ref: "#/components/schemas/tpp"
AuthErrorResponse:
description: type:Provides stringdetails of the authorization error. Includes OAuth 2.0
error properties
description: | type: object
required:
An OAuth2.0- orinteractionId
OIDC error - error
- error_description:
properties:
noRedirect:
type: string parametersdescription: An indicator that defines whether the End User -should $ref: '#/components/parameters/InteractionId'
be redirected back to the
responses: "303":Client due to the error. Please note that relates to an description:earlier |release and Heimdall and
A redirect URI thatis containstherefore the parameters required to indicatedeprecated for the errorCBUAE toimplementation.
type: boolean
the TPP. deprecated: true
error:
If an internal errordescription: occursThe duringerror processingcode ofas thedefined requestby an[RFC
`error` and 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
`error_description` parameters will be returned. type: string
error_description:
description: The redirecterror URIdescription mustas bedefined returnedby to[RFC
the User to redirect them back to the TPP. components: schemas:6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
InteractionId: descriptiontype: Uniquestring
identifier for the interaction with the User interactionId:
type: string AuthSuccessResponse$ref: '#/components/schemas/InteractionId'
typetpp: object
propertiesdescription: The TPP record as held by Ozone. interaction:
description: The properties of a successfully initiated interactionIf Ozone TPP Connect has been integrated into a
directory, the `directoryRecord` provides the TPP's directory type:record objectas held by Ozone in
properties: base 64 encoded format.
interactionIdtype: object
required:
$ref: '#/components/schemas/InteractionId'
- clientId
- orgId
params: - softwareStatementId
description: Query parameters unbundled- fromtppId
the original authorization request, including - tppName
- decodedSsa
query parameters, hash parameters, and properties of:
the JWT-Secured clientId:
Authorizationdescription: RequestThe (JAR)client sentidentifier infor the PushedTPP Authorizationas Request.issued by the Trust Framework
type: string
object pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
properties: client_idtppId:
description: The `client_id`identifier valueused thatby the callerAPI claimsHub to have.uniquely Atidentify thisthe stage,TPP
type: string
HeimdalltppName:
has verified that the `client_id` exists. type: string
description: The TPP name recorded in the Trust Framework
response_type: string
obieTppId:
description: The UK requestmarket grantTPP typeidentifier. This willproperty defaultis tonot `code``used for theCBUAE CBUAEand releaseis therefore
marked as deprecated.
as per the constraints of the FAPI 2.0 Security Profiletype: string
deprecated: true
typesoftwareStatementId:
string description: The software statement identifier for the Client.
enum: type: string
obieSoftwareStatementId:
- code description: The UK market software scope:statement identifier. This property is not used for CBUAE
type: string and is therefore marked as deprecated.
requesttype: string
deprecated: true
type: string obieSoftwareStatementName:
description: The UK market software scopes:statement name. This property is not used for CBUAE and
description: The requested scopes inis thetherefore Authorizationmarked Requestas deprecated.
type: string
type: array deprecated: true
directoryRecord:
items: type: string
description: The latest type:copy stringof the TPP directory record retrieve from the CBUAE Trust Framework
claims: directory, encoded as a Base 64 string
description: The requested claims in theformat: Authorizationbase64
Request. ssa:
typedescription: objectThe encoded Software Statement Assertion. This property is not used for CBUAE and claims:is
therefore marked type:as objectdeprecated.
statustype: string
typedeprecated: stringtrue
decodedSsa:
consentId: $ref: "#/components/schemas/softwareStatementProperties"
type: string orgId:
description: The Anorganization identifier for consentthe TPP
deprecatedtype: truestring
consentIdsList:
pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
type: array
softwareStatementProperties:
description: |
The decoded software statement retrieved Consent Ids associated with from the interaction.
Note that RAR requests may contain multiple consents. However, support for this is not required in the CBUAE 2024 standards and LFIs may considerTrust Framework that provides
the properties of the Client.
that this
array may have a single value. Please note:
items: - The JSON payload will contain other properties in addition to those listed
type: string tpp:here. The properties listed here are considered most relevant for activities $ref:
"#/components/schemas/tpp" AuthErrorResponse: such description:as ProvidesTPP detailslogo ofretrieval theand authorizationJWS errorverification.
Includes OAuth 2.0 - errorThe propertiescontent reflects elements of discovery metadata, type:which objectin generally
required: defined as a -file interactionIdrather than an API. Providing constraints such as
- error - error_description`minLength` and `maxLength` is impractical in this properties:context
noRedirect: The full software statement record is also available in the description:Trust AnFramework. indicator
that defines whether the End User should be redirectedPlease backalso torefer the Registration Framework page in the CBUAE standards for
Client due to the error. Please note that relates to an earlier release and Heimdall and
additional guidance on these properties.
type: object
properties:
is therefore deprecated for the CBUAE implementation. redirect_uris:
typedescription: booleanThe redirect URIs registered by the TPP at the Trust Framework
deprecated: true errortype: array
descriptionitems:
The error code as defined by [RFC type: string
6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)client_name:
typedescription: stringName of the Client to be presented to error_description:the End-User.
descriptiontype: string
The error description as defined by [RFC client_uri:
6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: stringdescription: URL of the home page of the Client.
type: string
interactionId: logo_uri:
$ref: '#/components/schemas/InteractionId' tppdescription: URL of the Client logo.
type: object descriptiontype: |string
Thejwks_uri: TPP
record as held by Ozone. description: URL of the IfClient OzoneJSON TPPWeb ConnectKey hasSet been(JWKS) integratedat intothe aTrust directory,Framework.
the `directoryRecord` provides the TPP's directory record as held by Ozonetype: instring
base 64 encoded format. client_id:
required: - clientIddescription: Unique Client Identifier.
- orgId type: string
- softwareStatementId roles:
- tppName description: The roles properties:under which the organization is registered at the Trust clientId:Framework.
type: stringarray
descriptionitems: The
client identifier for the TPP as issued by the Trust Frameworktype: string
orgIdsector_identifier_uri:
typedescription: stringURL using the https scheme to be used description: The organization identifier for the TPP
in calculating Pseudonymous Identifiers
softwareStatementId: by the OP. Allows redirect URI type:values stringto be grouped, easing registration
description: The software statement identifier for themanagement.
Client tppNametype: string
application_type: string
description: TheClient nameapplication oftype.
the TPP directoryRecordtype: string
organisation_id: type: string
description: TheOrganization latestidentifier copyfor oforganization the TPP directory record ifthat owns the TPPClient.
has registered with a directorytype: string
parameters:
InteractionId:
name: interactionId
description: Unique identifier for the interaction with the User
in: path
required: true
schema:
$ref: '#/components/schemas/InteractionId'
securitySchemes:
OzoneConnectJwtAuth:
description: |
Communications between the API Hub and the LFI Ozone Connect implementation are
secured using the "JWT Auth" mechanism, where the Client presents a signed JSON
Web Token as a credential.
The Server MUST verify the signature in order to authenticate the Client.
Please note that the value of the `scheme` parameter is not a registered HTTP
Authentication Scheme, to indicate it is specific to Ozone Connect. Please
refer to API Hub documentation for further details.
type: http
scheme: Ozone-Connect-JWT-Auth
|
...