...
| 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 * Added `client_id` and `request_uri` query parameters to `getAuth` operation
to provide guidance on
properties like `logo_uri` and `jwks_uri`
#### Changes#### Changes in Version 2024.3437.10
* Refactored Security`post` Schemeoperations Objects to use commona Path 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 Authorization
`login_hint` to Authorization Request parameters
description: Operations that#### supportChanges initiatingin the authorization of a UserVersion 2024.34.1
-* name:Refactored CompleteSecurity AuthorizationScheme Objects to use common description:definitions Operationsacross thatall supportAPI completingHub the
authorization of a User, APIs
indicating either success* orImplemented failurethe correct security:Security Requirements for -this {}API description,
- OzoneConnectJwtAuth: [] paths: reflecting /auth:security patterns available in API get: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
operationId: ThegetAuth
operation 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 status failure200. whereThe thebody OIDCcontains clienta hasJSON beenobject validatedwith 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 Client
institution 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 OIDC client successhas responsebeen thatvalidated financial
institutions are likely to be interested in: but validation of the parameters of the Authorization -Request `interactionfailed.interactionId`: 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**.
- `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.### Processing 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 ParametersHeimdall when this authorization request is completed by the financial Wheninstitution.
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
in the authorization request.of 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: |
This indicates that the parameters were successfully validated.
The financial institution should continue with the next stages of the interaction, using the `interactionId`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 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: |
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 asdeclines the uniqueauthorisation identifierof withconsent.
which
to track the interaction with the User The `doFail` operation updates the interaction state, generates an OIDC `error` content:
and returns the rest application/json:of the response that should be returned to the TPP.
schema: The financial institution can specify the `error` and `error_description` as
$ref: '#/components/schemas/AuthSuccessResponse' x-www-form-urlencoded parameters. If `error` "303":
and `error_description` omitted
description:then |default values will be returned in the redirect URI.
This indicates that the parameters wereHeimdall notreturns successfullya verified.303 with a redirect URI, which should be sent to the
However, there were no indications that theUser requestto originatedredirect fromthem anto invalidthe clientTPP.
requestBody:
The financial institutioncontent:
should respond to the customer with a redirect to the URI returned by the API application/x-www-form-urlencoded:
schema:
(including the query or hash parameters included in the URL) type: object
"400": properties:
description: | Thiserror:
indicates that the parameters were not successfully verified. type: string
Heimdall could not verify that the request originated from a valid client. description: |
The financial institution should render an error page and __must not__ redirect back to theAn TPPOAuth2.0 or OIDC error
content: error_description:
application/json: type: string
schema: parameters:
- $ref: '#/components/schemasparameters/AuthErrorResponseInteractionId'
/auth/{interactionId}/doConfirm:responses:
post"303":
operationId description: doConfirm|
tags: A redirect URI that -contains Completethe Authorizationparameters required to indicate the error to summary:
End an authorisation interaction with a success response the TPP.
description: | The `doConfirm`
operation should be called by the financial institution once the If an internal error occurs during processing userof interactionthe hasrequest beenan completed`error` and the
resource owner has authorized `error_description` access.parameters Thiswill operationbe updatesreturned.
the interaction state and generates an OIDC
Authorization Code value - `code` - and the rest of theThe responseredirect thatURI shouldmust be returned to the User to redirect them back returned to the TPP.
components:
schemas:
InteractionId:
When supported by Security Profile the financialdescription: institutionUnique canidentifier specifyfor the interaction with the User
set oftype: claimsstring
to be added to theAuthSuccessResponse:
ID Token. Heimdall creates an ID Tokentype: withobject
properties:
these claims along with any claims requiredinteraction:
by FAPI and OIDC. Please note that description: The properties of a successfully underinitiated theinteraction
FAPI 2.0 Security Profile ID Tokens are not supported in thetype: frontobject
channel, andproperties:
therefore will not be returned to the Client as the result of aninteractionId:
interaction. Please refer to the [Security Profile](https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#table-1)$ref: '#/components/schemas/InteractionId'
params:
for more details. Heimdall returnsdescription: aQuery 303parameters withunbundled afrom redirectthe uri.original Thisauthorization resourcerequest, ownerincluding should
be redirected to this URI. query parameters, hash parameters, and properties of ###the ParametersJWT-Secured
The request body can contain an arbitrary set ofAuthorization Request (JAR) sent in the Pushed Authorization Request.
`application/x-www-form-urlencoded` name-value pairs. These are added by type: object
Heimdall to the ID Token. The claim name is set to the parameter name andproperties:
the claim value to the parameter value. client_id:
Claim names prefixed by `heimdall.` act as control parameters for thedescription: tokensThe `client_id` value that the caller claims to have. At thatthis arestage,
produced. These claims are not added to the ID Token. requestBody: Heimdall has verified that the content:`client_id` exists.
application/x-www-form-urlencoded: type: string
schema: response_type:
description: Where supported, allows a financial institution to send parameters description: The request grant type. This will default to that`code` controlfor the lifetimeCBUAE release of
Access Tokens and availability of as Refreshper Tokens.the Theseconstraints featuresof arethe notFAPI supported2.0 forSecurity theProfile
UAE Open Financetype: Framework.string
Financial institutions can, however, add claims that will enum:
be included in an ID Token, which can be requested by a TPP dependent on the- OAuthcode
scope:
granted by the User. type: string
object additionalPropertiesrequest:
true parameters: - $reftype: '#/components/parameters/InteractionId'string
responses: "303":scopes:
description: |
The requested scopes in the Authorization Request
A redirect URI that contains an authorization codetype: alongarray
with additional parameters as required byitems:
OIDC. If an internal error occurs during processingtype: ofstring
the request an `error` and claims:
`error_description` parameters will be returned. description: The requested claims in the Authorization Request.
The redirect URI must be returned to the User to redirect them back totype: theobject
TPP. /auth/{interactionId}/doFail: post: operationIdlogin_hint:
doFail tags: - Complete Authorizationdescription: The value of the `login_hint` parameter summary:sent Endin anthe authorisationPushed interactionAuthorization with
a failure response description: | Therequest. `doFail`This operationvalue shouldis beexpected calledto bybe theencrypted financialas institutiona onceJWE.
the User interaction has been completed and has resulted intype: astring
failure to grant accessclaims:
to the TPP. Examples failure scenarios include: type: object
* The User does not authenticate successfully. status:
* The User declines the authorisation of consent. type: string
The `doFail` operation updates the interaction state, generates anconsentId:
OIDC `error` and returns the resttype: ofstring
the response that should be returned to the TPP. description: An identifier for Theconsent
financial institution can specify the `error` and `error_description` as deprecated: true
x-www-form-urlencoded parameters. If `error` and `error_description` omitted consentIdsList:
then default values will be returned in the redirecttype: URI.array
Heimdall returns a 303 with adescription: redirect|
URI, which should be sent to the User toConsent redirectIds themassociated towith the TPPinteraction.
requestBody: content:Note that RAR requests may contain multiple consents. application/x-www-form-urlencoded:
schema:
However, support for this is not required in the CBUAE 2024 standards and LFIs may consider
type: object that this array may have a single value.
properties: items:
error: type: string
typetpp:
string $ref: "#/components/schemas/tpp"
AuthErrorResponse:
description: |Provides details of the authorization error. Includes OAuth 2.0
error properties
An OAuth2.0 or OIDC errortype: object
required:
error_description:- interactionId
- error
type: string- error_description
parametersproperties:
noRedirect:
- $ref: '#/components/parameters/InteractionId' responsesdescription: An indicator that defines whether the End User "303":should be redirected back to the
description: | Client due to the error. Please Anote redirectthat URIrelates thatto containsan theearlier parametersrelease requiredand toHeimdall indicateand
the error to is therefore deprecated for the TPPCBUAE implementation.
type: boolean
deprecated: Iftrue
an internal error occurs during processing of the requesterror:
an `error` and description: The error code as defined `error_description` parameters will be returned.by [RFC
6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: string
The redirect URI must be returnederror_description:
to the User to redirect them back to the TPP. componentsdescription: The error description schemas:as defined by [RFC
InteractionId: description: Unique identifier for the interaction with the User 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: string
AuthSuccessResponse: interactionId:
type: object properties$ref: '#/components/schemas/InteractionId'
interaction:
tpp:
description: The propertiesTPP ofrecord aas successfullyheld initiatedby interactionOzone. If Ozone TPP Connect has been integrated into a
type: object directory, the `directoryRecord` provides properties:the TPP's directory record as held by Ozone in
interactionId: base 64 encoded format.
$reftype: '#/components/schemas/InteractionId'object
required:
params: - clientId
- description: QueryorgId
parameters unbundled from the original authorization request, including - softwareStatementId
- tppId
query parameters, hash parameters,- andtppName
properties of the JWT-Secured - decodedSsa
properties:
Authorization Request (JAR) sent inclientId:
the Pushed Authorization Request. description: The client identifier for the TPP type:as objectissued by the Trust Framework
propertiestype: string
client_id: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}$'
tppId:
description: The `client_id`identifier valueused thatby the callerAPI claimsHub to have. At this stage,
Heimdall has verified that the `client_id` exists.
uniquely identify the TPP
type: string
response_type:
tppName:
description: The requestTPP grantname type.recorded Thisin willthe defaultTrust toFramework
`code`` for the CBUAE release type: string
obieTppId:
as per the constraints of thedescription: FAPIThe 2.0UK Securitymarket ProfileTPP identifier. This property is not used for CBUAE and is therefore
type: string marked as deprecated.
enumtype: string
deprecated: true
- codesoftwareStatementId:
scopedescription: The software statement identifier for the Client.
type: string
string
obieSoftwareStatementId:
request: description: The UK market software statement identifier. This property is not used for CBUAE
type: string and is therefore marked as deprecated.
scopes: type: string
description: The requested scopesdeprecated: intrue
the Authorization Request obieSoftwareStatementName:
description: The type:UK arraymarket software statement name. This property is not used for CBUAE and
items: is therefore marked as deprecated.
type: string
deprecated: true
claims directoryRecord:
type: string
description: The requestedlatest claimscopy inof the AuthorizationTPP Request.directory record retrieve from the CBUAE Trust Framework
type: object directory, encoded as a Base 64 string
additionalPropertiesformat: truebase64
ssa:
additionalProperties: true description: The encoded Software Statement Assertion. This property is claims:not used for CBUAE and is
type: object therefore marked as deprecated.
status: type: 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
|
...