...
| 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 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.
### Changes#### Changes in Version 20242025.4606.0
* AddedChanged additional`interactionId` properties to theoptional `tpp`for dataerror providedresponses in the `get /auth` response
*operation
Added
details on content of `decodedSsa`#### propertyChanges toin provide guidance onRelease 2024.48.0
* Added health propertiescheck likeendpoint `logo_uri` and `jwks_uri`GET /hello-mtls
### #### 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 * Added details on content of `decodedSsa` property to provide guidance on
properties like `logo_uri` and `jwks_uri`
#### Changes in Version 2024.37.0
* Refactored `post` operations to use a Path parameter
* Refined descriptions to add clarity for readers
* Removed `additionalProperties: true` as not required and causes tooling issues
* Added `login_hint` to Authorization Request parameters
#### Changes in Version 2024.34.1
* Refactored Security Scheme Objects to use common definitions across all API Hub
APIs
* Implemented the correct Security Requirements for this API description,
reflecting security patterns available in API Hub
version: 20242025.4606.0
tags:
- name: Initiate Authorization
description: Operations that support initiating the authorization of a User
- name: Complete Authorization
description: Operations that support completing the authorization of a User,
indicating either success or failure
- name: health-check
description: Operations that support checking the health of the API Hub
security:
- {}
- OzoneConnectJwtAuth: []
paths:
/auth:
get:
tags:
- Initiate Authorization
summary: Initiate an authorisation interaction
operationId: getAuth
description: |
The `getAuth` operation should be called by the financial institution at the beginning of the
interaction. The operation validates all the parameters that are passed to it to ensure that the
authorization request is FAPI compliant and has only the client_id` and `redirect_uri` parameters.
The operation responds with one of the three outcomes:
- __Success__: The operation returns a status 200. The body contains a JSON object with the
interaction and all the query parameters extracted from the OIDC request object.
- __Non-redirectable failure__: This indicates a failure where validation of the OIDC Client
failed. The financial institution should render an error page and end the interaction.
- __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 redirect, which the financial institution must use to redirect the User **without modification**.
### 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 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
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 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 declines the authorisation of consent.
The `doFail` operation updates the interaction state, generates an OIDC `error`
and returns the rest of the response that should be returned to the TPP.
The financial institution can specify the `error` and `error_description` as
x-www-form-urlencoded parameters. If `error` and `error_description` omitted
then default values will be returned in the redirect URI.
Heimdall returns a 303 with a redirect URI, which should be sent to the
User to redirect them to the TPP.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
error:
type: string
description: |
An OAuth2.0 or OIDC error
error_description:
type: string
parameters:
- $ref: '#/components/parameters/InteractionId'
responses:
"303":
description: |
A redirect URI that contains the parameters required to indicate the error to
the TPP.
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.
components:
schemas/hello-mtls:
InteractionIdget:
descriptionoperationId: UniquehelloMtls
identifier for the interaction with the Usertags:
type: string - health-check
AuthSuccessResponse: typesummary: objectcheck connectivity including mtls and provides information properties:about the client cert that the server received
interaction: description:
description: The properties ofThis ahealth successfullycheck initiatedis interactionused to check that the end-to-end network connectivity is working as type:expected objectincluding mutual tls.
properties:This health check endpoint assists in debugging mutual tls client issues.
interactionId: The health check returns information about the client certificate $ref: '#/components/schemas/InteractionId'
and the issuer of the client certificate that the server received.
params: responses:
description: Query parameters unbundled from the original authorization request, including'200':
description: OK
content:
query parameters, hash parameters, and properties of the JWT-Secured application/json:
schema:
Authorization Request (JAR) sent in the Pushed Authorization Request. $ref: '#/components/schemas/HealthCheckCertResponse'
components:
typeschemas:
object InteractionId:
description: Unique identifier for properties:the interaction with the User. Please note
that client_id:this identifier may not be returned with errors from the `get /auth`
description: Theoperation `client_id` value that as the callerinteraction claimsmay tonot have. Atbeen thisinitiated stage,due to an invalid
request.
type: string
Heimdall has verified that theAuthSuccessResponse:
`client_id` exists. type: object
properties:
type: string interaction:
description: The properties response_type:
of a successfully initiated interaction
type: object
description: The request grant type. This willproperties:
default to `code` for the CBUAE release interactionId:
as per the constraints of the FAPI 2.0 Security Profile$ref: '#/components/schemas/InteractionId'
params:
typedescription: stringQuery parameters unbundled from the original authorization request, including
enum: query parameters, hash parameters, and properties of the JWT-Secured
- code Authorization Request (JAR) sent in the Pushed Authorization scope:Request.
type: stringobject
properties:
request: client_id:
type: string description: The `client_id` scopes:value that the caller claims to have. At this stage,
description: The requested scopes in the Authorization Request Heimdall has verified that the `client_id` exists.
type: array type: string
items: response_type:
type: string description: The request grant type. This will default to `code` for the claims:CBUAE release
description: The requested claimsas inper the Authorizationconstraints Request.of the FAPI 2.0 Security Profile
type: object type: string
login_hint: enum:
description: The value of the `login_hint` parameter sent in the- Pushedcode
Authorization scope:
request. This value is expected to be encrypted as a JWE. type: string
type: string request:
claims: type: string
type: object scopes:
status: typedescription: stringThe requested scopes in the Authorization Request
consentId: type: array
type: string descriptionitems:
An identifier for consent deprecated type: truestring
consentIdsList: claims:
type: array description: The requested claims in the Authorization Request.
description: | Consenttype: Idsobject
associated with the interaction. login_hint:
Note that RAR requests may contain multiple consents. However, support for this is not required indescription: theThe CBUAEvalue 2024of standardsthe and`login_hint` LFIsparameter maysent considerin the Pushed Authorization
that this array may have a single valuerequest. This value is expected to be encrypted as a JWE.
items: type: string
tpp: claims:
$ref: "#/components/schemas/tpp" AuthErrorResponsetype: object
description: Provides details of the authorizationstatus:
error. Includes OAuth 2.0 error properties type: string
type: object requiredconsentId:
- interactionId type: string
- error - error_description: An identifier for consent
properties: noRedirect: deprecated: true
description: An indicator that defines whether theconsentIdsList:
End User should be redirected back to the type: array
Client due to the error. Please note that relates todescription: an|
earlier release and Heimdall and Consent isIds thereforeassociated deprecatedwith for the CBUAE implementationinteraction.
type: boolean Note that RAR requests may contain deprecated:multiple trueconsents. However, support for this is not required in error:the CBUAE 2024 standards and LFIs may consider
description: The error code as defined by [RFC that this array may have a 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)single value.
type: string items:
error_description: descriptiontype: string
The error description as defined by [RFC tpp:
6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)$ref: "#/components/schemas/tpp"
AuthErrorResponse:
type: string description: Provides details of the authorization error. Includes interactionId:OAuth 2.0
error $ref: '#/components/schemas/InteractionId'properties
tpptype: object
description required:
The TPP record as held by Ozone. If Ozone- TPPerror
Connect has been integrated into a - error_description
directory, theproperties:
`directoryRecord` provides the TPP's directory record as held bynoRedirect:
Ozone in description: baseAn 64indicator encodedthat format.defines whether the End User should be type:redirected objectback to the
required: Client -due clientIdto the error. Please note that relates to an -earlier orgIdrelease and Heimdall and
- softwareStatementId is therefore deprecated -for tppIdthe CBUAE implementation.
- tppName type: boolean
- decodedSsa deprecated: true
properties: clientIderror:
description: The client identifier for the TPP as issued by the Trust Framework error code as defined by [RFC
6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: string
error_description:
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}$' description: The error description as defined by [RFC
6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)
type: string
interactionId:
$ref: '#/components/schemas/InteractionId'
tpp:
description: The TPP record as held by Ozone. If Ozone TPP Connect has been integrated into a
directory, the `directoryRecord` provides the TPP's directory record as held by Ozone in
base 64 encoded format.
type: object
required:
- clientId
- orgId
- softwareStatementId
- tppId
- tppName
- decodedSsa
properties:
clientId:
description: The client identifier for the TPP as issued by the Trust Framework
type: string
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 identifier used by the API Hub to uniquely identify the TPP
type: string
tppName:
description: The TPP name recorded in the Trust Framework
type: string
obieTppId:
description: The UK market TPP identifier. This property is not used for CBUAE and is therefore
marked as deprecated.
type: string
deprecated: true
softwareStatementId:
description: The software statement identifier for the Client.
type: string
obieSoftwareStatementId:
description: The UK market software statement identifier. This property is not used for CBUAE
and is therefore marked as deprecated.
type: string
tppIddeprecated: true
obieSoftwareStatementName:
description: The identifier used by the API Hub to uniquelydescription: identifyThe theUK TPPmarket software statement name. This property is not used for CBUAE type:and
string tppName: is therefore marked as deprecated.
description: The TPP name recorded in the Trusttype: Frameworkstring
typedeprecated: stringtrue
obieTppIddirectoryRecord:
descriptiontype: string
The UK market TPP identifier. This property is not useddescription: forThe CBUAElatest andcopy isof thereforethe TPP directory record retrieve from the CBUAE Trust Framework
marked as deprecated. directory, encoded as a Base type:64 string
deprecatedformat: truebase64
softwareStatementIdssa:
description: The softwareencoded statementSoftware identifier for the ClientStatement Assertion. This property is not used for CBUAE and is
type: string obieSoftwareStatementId: therefore marked as deprecated.
description: The UK market softwaretype: statementstring
identifier. This property is not used for CBUAE deprecated: true
anddecodedSsa:
is therefore marked as deprecated. $ref: "#/components/schemas/softwareStatementProperties"
type: string orgId:
deprecated: true description: The organization identifier for the obieSoftwareStatementName:TPP
descriptiontype: Thestring
UK market software statement name. This property is not used for CBUAE andpattern: '^[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}$'
softwareStatementProperties:
description: is|
therefore marked as deprecated. The decoded software statement retrieved from type:the stringTrust Framework that provides
deprecated: truethe properties of the Client.
directoryRecord: Please note:
type: string - The JSON payload will description:contain Theother latestproperties copyin ofaddition theto TPPthose directorylisted
record retrieve from the CBUAE Trust Framework here. The properties listed here are considered most directory,relevant encodedfor asactivities
a Base 64 string such format: base64as TPP logo retrieval and JWS verification.
ssa: - The content description:reflects Theelements encodedof Softwarediscovery Statementmetadata, Assertion.which Thisin propertygenerally
is not used for CBUAE and is defined as a file rather than an thereforeAPI. markedProviding asconstraints deprecated.such as
type: string `minLength` and `maxLength` is impractical in this context
deprecated: true The full decodedSsa:software statement record is also available in the Trust Framework.
$ref: "#/components/schemas/softwareStatementProperties" Please also refer orgId:the Registration Framework page in the CBUAE standards for
description: The organization identifier for the TPPadditional guidance on these properties.
type: stringobject
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:
softwareStatementProperties:redirect_uris:
description: The |redirect URIs registered by the TPP at the Trust Framework
The decoded software statement retrieved from the Trust Frameworktype: thatarray
provides theitems:
properties of the Client. type: string
Please note:client_name:
description: Name of the Client to be presented to the End- The JSON payload will contain other properties in addition to those listedUser.
type: string
client_uri:
description: URL of the home page of the hereClient.
The properties listed here are considered most relevant fortype: activitiesstring
logo_uri:
such as TPP logo retrieval and JWSdescription: verification.URL of the Client logo.
- The content reflects elementstype: ofstring
discovery metadata, which in generally jwks_uri:
defined as adescription: fileURL ratherof thanthe anClient API.JSON ProvidingWeb constraintsKey suchSet as(JWKS) at the Trust Framework.
`minLength` and `maxLength`type: isstring
impractical in this context client_id:
The full software statement record is alsodescription: availableUnique inClient theIdentifier.
Trust Framework. type: Pleasestring
also refer the Registration Framework page in the CBUAEroles:
standards for additionaldescription: guidanceThe onroles theseunder properties.which the organization is registered at the type:Trust objectFramework.
properties: type: array
redirect_uris: items:
description: The redirect URIs registered by the TPP at thetype: Truststring
Framework sector_identifier_uri:
type: array description: URL using the items:https scheme to be used in calculating Pseudonymous Identifiers
type: string by client_name:
description: Name of the Client to be presented to the End-Userthe OP. Allows redirect URI values to be grouped, easing registration
management.
type: string
clientapplication_uritype:
description: URLClient of the home page of the Clientapplication type.
type: string
logoorganisation_uriid:
description: Organization identifier for description:organization URLthat ofowns the Client logo.
type: string
HealthCheckCertResponse:
jwks_uri: properties:
descriptionconnectionEstablished:
URL of the Client JSON Web Key Set (JWKS) at thetype: Trustboolean
Framework.
mtlsStatus:
type: string client_idtype: string
descriptionenum:
Unique Client Identifier. - type:established
string roles: - not-established
description: The roles underhostName:
which the organization is registered at the Trust Framework. type: arraystring
itemsclientCertificate:
type: stringobject
sector_identifier_uri: properties:
description: URL using the httpssubject:
scheme to be used in calculating Pseudonymous Identifiers type: string
by the OP. Allows redirect URI values to beissuer:
grouped, easing registration type: management.string
typerequired:
string application_type: - subject
description: Client application type. - issuer
typerequired:
string - organisation_id:connectionEstablished
- mtlsStatus
description: Organization identifier for organization that owns- thehostName
Client. type: string- clientCertificate
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
|
...