...
| 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 Removedprovide `additionalProperties: true` as not required and causes tooling issuesguidance on
properties like *`logo_uri` Addedand `login_hint` to Authorization Request parameters`jwks_uri`
#### Changes #### Changes in Version 2024.3437.10
* Refactored Security`post` Scheme Objectsoperations to use commona definitions across all API Hub APIsPath parameter
* ImplementedRefined thedescriptions correctto Securityadd Requirementsclarity for thisreaders
API
description, reflecting security patterns available* inRemoved API`additionalProperties: Hubtrue` as not required version: 2024.37.0
tags:and causes tooling issues
- name: Initiate Authorization* Added `login_hint` to Authorization description:Request Operationsparameters
that
support initiating the authorization of#### aChanges Userin Version 2024.34.1
-
name: Complete Authorization * Refactored Security description:Scheme OperationsObjects thatto supportuse completingcommon thedefinitions authorizationacross ofall aAPI User,Hub
indicating eitherAPIs
success
or failure security: * Implemented -the {}correct Security Requirements -for OzoneConnectJwtAuth:this []API description, paths:
/auth: reflecting get:security patterns available in API Hub
tags: 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
TheoperationId: operationgetAuth
responds with one of the three outcomesdescription: |
- __Success__: The The `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 financialoperation institutionresponds shouldwith renderone anof errorthe page and end the interaction.three outcomes:
- __Redirectable failureSuccess__: The Thisoperation indicatesreturns a failure where the OIDC client has been validated status 200. The body contains a JSON object with the
butinteraction validationand ofall the query parameters extracted offrom the AuthorizationOIDC Requestrequest failedobject.
The
operation therefore - __Non-redirectable failure__: respondsThis withindicates a failure 303where redirect,validation whichof the financialOIDC institutionClient
must use to redirect the User **without modification**.
### Processing a success response failed. The financial institution should render an error page and end the interaction.
- __Redirectable failure__: ThereThis areindicates twoa propertiesfailure inwhere the successOIDC responseclient thathas financialbeen institutionsvalidated are
likely to be interested in: but validation of the parameters of - `interaction.interactionId`:the Authorization Request failed. The interactionoperation identifiertherefore that
should be used with 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.
### Parameters
When calling this API, the financial institution must pass on **all the query parameters or hash parameters** received from the TPPa 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 when this authorization request is completed by the financial institution.
- `tpp.directoryRecord`: Where Ozone is integrated with a Directory Service, this contains a record
inof the authorization requestTPP record as held on the directory. The FAPI 2.0 Security Profile states that a Client will **_only_** send the `client_id` and `request_uri` values, as structure of the record will depend on the directory. Directory record as held by Ozone in base 64 encoded format.
### Parameters
When calling specifiedthis by the [Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#section-5API, the 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). 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 authoritative source for making that decision, hence allThe queryredirect parametersURI must be passed on. No query parameters are therefore
returned to the User to redirect them back to the TPP.
/auth/{interactionId}/doFail:
post:
defined hereoperationId: asdoFail
a result. tags:
responses: - Complete Authorization
"200": summary: End an authorisation interaction description:with |a failure response
description: |
This indicates that the parameters were successfully validated.The `doFail` operation should be called by the financial institution once the
The financial institution should continue with the nextUser stagesinteraction ofhas thebeen interaction,completed usingand thehas `interactionId`resulted in a failure to grant
as the uniqueaccess identifierto withthe whichTPP. toExamples trackfailure thescenarios interactioninclude:
with
the User * The User does not content:authenticate successfully.
* The application/json:User declines the authorisation of consent.
schema:The `doFail` operation updates the interaction state, generates an OIDC `error`
$ref: '#/components/schemas/AuthSuccessResponse' and returns the rest of the response that "303":should be returned to the TPP.
description: | The financial institution can specify the `error` and `error_description` as This
indicates that the parameters were not successfully verified.
x-www-form-urlencoded parameters. If `error` and `error_description` omitted
However, there were nothen indicationsdefault thatvalues thewill requestbe originatedreturned fromin anthe invalidredirect clientURI.
Heimdall returns a 303 with a Theredirect financialURI, institutionwhich should respondbe sent to the
customer with a redirect to the URI returned byUser theto APIredirect them to the TPP.
requestBody:
(including the query or hash parameters included in thecontent:
URL) "400"application/x-www-form-urlencoded:
description schema:
| This indicates thattype: theobject
parameters were not successfully verified. properties:
Heimdall could not verify that the request originated from a valid client. error:
The financial institution should render an error pagetype: andstring
__must not__ redirect back to the TPP. contentdescription: |
application/json: An OAuth2.0 or OIDC error
schema: error_description:
$ref: '#/components/schemas/AuthErrorResponse' /auth/{interactionId}/doConfirm: post: operationIdtype: string
doConfirm
tagsparameters:
- Complete Authorization $ref: '#/components/parameters/InteractionId'
summaryresponses:
End an authorisation interaction with"303":
a success response description: |
The `doConfirm` operationA shouldredirect beURI calledthat bycontains the parameters financialrequired institutionto onceindicate the error to
user interaction has been completed and the resourceTPP.
owner has authorized access.
This operation updates the interaction state and generates an OIDC If an internal error occurs during Authorizationprocessing Codeof valuethe -request `code`an -`error` and the
rest of the response that should be `error_description` parameters will be returned.
to the TPP. When
supported by Security Profile the financial institution can specify the The redirect URI must be returned to setthe ofUser claimsto toredirect bethem addedback to the ID TokenTPP.
Heimdallcomponents:
creates an IDschemas:
Token with InteractionId:
thesedescription: claimsUnique alongidentifier withfor anythe claimsinteraction requiredwith bythe FAPIUser
and OIDC. Please note that type: string
AuthSuccessResponse:
under the FAPI 2.0 Security Profiletype: IDobject
Tokens are not supported in the frontproperties:
interaction:
channel, and therefore will not be returned to the Client asdescription: theThe resultproperties of ana successfully initiated interaction
interaction. Please refer to the [Security Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#table-1)
type: object
properties:
for more details. interactionId:
Heimdall returns a 303 with a redirect uri. This resource owner should be$ref: '#/components/schemas/InteractionId'
redirected to thisparams:
URI. ### Parameters description: Query parameters unbundled from the original Theauthorization request body can contain an arbitrary set of
`application/x-www-form-urlencoded` name-value pairs. These are added by, including
query parameters, hash parameters, and properties of the JWT-Secured
Heimdall to theAuthorization ID Token. The claim name is set to the parameter name and theRequest (JAR) sent in the Pushed Authorization Request.
claimtype: valueobject
to the parameter value. Claim namesproperties:
prefixed by `heimdall.` act as control parameters for the tokens client_id:
that are produced. These claims are not added to the ID Token. description: The `client_id` requestBody:value that the caller claims to have. At this content:stage,
application/x-www-form-urlencoded: Heimdall has verified schema:that the `client_id` exists.
description: Where supported, allows a financial institution totype: sendstring
parameters response_type:
that control the lifetime of Access Tokens and availability of description: The request grant type. This will default Refreshto Tokens.`code` Thesefor featuresthe areCBUAE notrelease supported
for the UAE Open Financeas Framework.per Financialthe institutionsconstraints can,of however,the addFAPI claims2.0 thatSecurity willProfile
be included intype: anstring
ID Token, which can be requested by a TPP dependent on the OAuth enum:
scope granted by the User. - code
type: object parametersscope:
- $ref: '#/components/parameters/InteractionId' responsestype: string
"303": request:
description: | Atype: redirectstring
URI that contains an authorization code along with additional scopes:
parameters as required by OIDC. description: The requested scopes in Ifthe anAuthorization internalRequest
error occurs during processing of the request an `error` and type: array
`error_description` parameters will be returned. items:
The redirect URI must be returned totype: thestring
User to redirect them back to the TPP. /auth/{interactionId}/doFail: postclaims:
operationId: doFail tags: description: The requested claims -in Completethe Authorization Request.
summary: End an authorisation interaction with a failure response type: object
description: | The `doFail` operation should be called by the financial institution once thelogin_hint:
User interaction has been completed anddescription: hasThe resultedvalue inof athe failure`login_hint` toparameter grantsent in the Pushed Authorization
access to the TPP. Examples failure scenarios include: request. *This Thevalue Useris doesexpected notto authenticatebe successfully.encrypted as a JWE.
* The User declines the authorisation of consent. type: string
The `doFail` operation updates the interaction state, generates an OIDCclaims:
`error` and returns the rest oftype: theobject
response that should be returned to the TPP. status:
The financial institution can specify the `error` and `error_description` as type: string
x-www-form-urlencoded parameters. If `error` and `error_description`consentId:
omitted then default values will betype: returnedstring
in the redirect URI. Heimdall returnsdescription: aAn 303identifier withfor aconsent
redirect URI, which should be sent to the deprecated: true
User to redirect them to the TPP. consentIdsList:
requestBody: content: type: array
application/x-www-form-urlencoded: description: |
schema: Consent type:Ids objectassociated with the interaction.
properties: Note that RAR requests may contain multiple consents. However, support for this error:is not required in the CBUAE 2024 standards and LFIs may consider
type: string that this array may have a single value.
description: | items:
An OAuth2.0 or OIDC error type: string
tpp:
error_description: $ref: "#/components/schemas/tpp"
AuthErrorResponse:
typedescription: stringProvides details of the authorization error. Includes OAuth parameters:2.0
- $ref: '#/components/parameters/InteractionId'
error properties
responsestype: object
"303"required:
- description:interactionId
| - error
A redirect URI that contains the- parameterserror_description
required to indicate the error to properties:
noRedirect:
the TPP. description: An indicator that defines whether the End User should be redirected back to the
If an internal error occurs during processing of theClient requestdue anto `error`the anderror. Please note that relates to an earlier release and Heimdall and
`error_description` parameters will be returned. is therefore deprecated for the CBUAE implementation.
type: boolean
The redirect URI must be returned to the User todeprecated: redirecttrue
them back to the TPP. components: schemaserror:
InteractionId: description: UniqueThe identifiererror forcode theas interactiondefined withby the[RFC
User type: string AuthSuccessResponse:6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: object properties:type: string
interactionerror_description:
description: The error description propertiesas ofdefined aby successfully[RFC
initiated interaction type: object6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
propertiestype: string
interactionId:
$ref: '#/components/schemas/InteractionId'
tpp:
paramsdescription: The TPP record as held by Ozone. If Ozone description: Query parameters unbundled from the original authorization request, including
TPP Connect has been integrated into a
directory, the `directoryRecord` provides the TPP's querydirectory parameters,record hashas parameters,held andby propertiesOzone ofin the
JWT-Secured base 64 encoded format.
Authorizationtype: Requestobject
(JAR) sent in the Pushed Authorization Request.required:
- clientId
type: object - orgId
- softwareStatementId
properties: - tppId
client_id: - tppName
- decodedSsa
descriptionproperties:
The `client_id` value that the caller claims to have.clientId:
At this stage, description: The client identifier for the TPP as issued by the Trust Framework
Heimdall has verified that the `client_id` exists. type: string
pattern: type: string'^[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}$'
response_type:
tppId:
description: The requestidentifier grantused type.by Thisthe willAPI defaultHub to `code`uniquely foridentify the CBUAETPP
release as per the constraints of the FAPI 2.0 Security Profiletype: string
tppName:
typedescription: stringThe TPP name recorded in the Trust Framework
type: enum:string
obieTppId:
description: -The codeUK market TPP identifier. This property is not used for CBUAE and is therefore
scope: marked as deprecated.
type: string type: string
deprecated: true
request: softwareStatementId:
typedescription: stringThe software statement identifier for the Client.
scopestype: string
obieSoftwareStatementId:
description: The requestedUK scopesmarket insoftware thestatement Authorization Request
identifier. This property is not used for CBUAE
type: array and is therefore marked as deprecated.
itemstype: string
deprecated: true
typeobieSoftwareStatementName:
string description: The UK market software statement name. claims:This property is not used for CBUAE and
description: The requested claimsis intherefore themarked Authorizationas Requestdeprecated.
type: string
type: object deprecated: true
directoryRecord:
login_hint: type: string
description: The latest valuecopy of the `login_hint` parameter sent in the PushedTPP Authorizationdirectory record retrieve from the CBUAE Trust Framework
directory, request.encoded Thisas valuea isBase expected64 tostring
be encrypted as a JWE. format: base64
ssa:
type: string description: The encoded Software Statement Assertion. claims:This property is not used for CBUAE and is
type: object therefore marked as deprecated.
status: type: string
type: string deprecated: true
consentIddecodedSsa:
$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
|
...