...
| 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 the OAS3 specification 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 for an financial institution to develop the user interface for customers without
having to deal with the complexities of OIDC and FAPI and without having to gain a
thorough understanding of the constraints placed by FAPI.
__Version 2.2 Release 2024.31__
The interface consists of end-points
- The __Headless Authorization End-point__ `GET /auth` should be called by the financial institution at the
begining of an authorization code grant. This is typically immediately after it receives an authorization
request from a TPP
- The __Confirmation End-point__ `POST /auth/:interactionId/doConfirm` should be called by the
financial institution to notify Heimdall that an interaction has completed successfully.
- The __Failure End-point__ `POST /auth/:interactionId/doFail` should be called by the financial institution
to notify Heimdall that the interaction has failed.
#### Coming soon
The following changes can be expected in the next release:
- some enumeration and object definitions remain to be aligned with CBUAE specifications. These will be updated
- specific changes expected in the next release have been marked as ***TODO*** in the document
version: Release 2024.31
tags:
- name: headless-heimdall
paths:
/auth:
get:
tags:
- headless-heimdall
summary: Start an authorisation interaction
description: |
The Headless Authorization End-point should be called by the financial institution at the beginning of the
interaction.
The end-point validates all the parameters that are passed to it to ensures that the
authorization request is FAPI compliant, valid, correctly signed and has the
appropriate client_id, redirect_uri etc.
The end-point responds with one of the three outcomes:
- __Success__: The end-point 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 to verify that the end-point was called
through a valid OIDC client. The financial institution should render an error page and end the interaction.
- __Redirectable failure__: This indicates a failure where the end-point was called by a potentially valid OIDC client.
Headless Heimdall responds with a 303 redirect. The financial institution must respond to the TPP with the same redirect without any modifications.
### Processing a success response
There are three key fields in the success response that financial institutions are likely to be interested in:
- `interaction.interactionId`: This is the interaction identifier that should be used with
subsequent calls to Headless Heimdall when this authorization request is completed by the financial institution.
- `interaction.params.claims.id_token.openbanking_intent_id`: If this interaction is for a UK OBIE consent
authorisation, the Consent Id is contained in this field. The financial institution can use the Ozone Consent Manager API
to retrieve the consent
- `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
OAS3 does not have a way to indicate a flexible set of query parameters.
When calling this API, the financial institution should pass on all the query parameters or hash parameters received from the TPP
in the authorization request.
operationId: headlessAuthorization
responses:
"200":
description: |
This indicates that the parameters were successfully validated.
The financial institution should continue with the next stages of the interaction, keeping track of the
returned interactionId.
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.
The financial institution __must not__ redirect back to the TPP.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthErrorResponse'
security:
- bearerAuth: []
/auth/:interactionId/doConfirm:
post:
operationId: doConfirm
tags:
- headless-heimdall
summary: Ends an authorisation interaction with a success response
description: |
The Confirmation End-point should be called by the financial institution once the user interaction
has been completed and the resource owner has authorized access.
The doConfirm call updates the interaction state generates an OIDC `code` and the rest of the
response that should be returned to the TPP.
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.
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:
type: object
properties:
"heimdall.suppressRefreshToken":
type: boolean
description: |
Suppresses the generation of a refresh token.
If set to true, a refresh token is not generated.
If set to false, a refresh token is generated only if Heimdall has been
configured to support the refresh_token grant type.
If not specified, Heimdall treats this as false.
Note that this feature *must not* be used for CBUAE
"heimdall.accessTokenValidity":
type: integer
description: |
Specifies (in no of seconds) how long the generated access token should be valid for.
If not specified, the system default is used.
Note that this feature *must not* be used for CBUAE
"heimdall.refreshTokenValidity":
type: integer
description: |
Specifies (in number of seconds) how long the generated refresh token
should be valid for.
If not specified, the system default is used.
Note that this feature *must not* be used for CBUAE
additionalProperties: true
parameters:
- $ref: '#/components/parameters/interactionId'
responses:
"303":
description: |
Heimdall returns a redirect uri that contains an authorization code along with
additional parameters as required by OIDC.
In case an internal error occurred while processing the request, heimdall returns
an error parameter.
In both cases, the financial institution must redirect the resource owner to the redirect uri.
security:
- bearerAuth: []
/auth/:interactionId/doFail:
post:
operationId: doFail
tags:
- headless-heimdall
summary: Ends an authorisation interaction with a failure response
description: |
The failure End-point should be called by the financial institution once the user interaction
has been completed and has resulted in a failure to gain access.
(e.g. when the user declines to authorise, does not provide the appropriate credentials etc.)
The doFail call updates the interaction state, generates an OIDC `error` and 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.
Heimdall returns a 303 with a redirect uri. This resource owner should be redirected to this URI.
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: |
Heimdall returns a redirect uri that contains an authorization code along with
additional parameters as required by OIDC.
In case an internal error occurred while processing the request, heimdall returns
an error parameter.
In both cases, the financial institution must redirect the resource owner to the redirect uri.
security:
- bearerAuth: []
components:
schemas:
AuthSuccessResponse:
type: object
properties:
interaction:
type: object
properties:
interactionId:
type: string
description: An identifier for this interaction
params:
description: |
Query parameters unbunbled from the original authorization request.
This includes both query parameters and hash parameters.
This also includes parameters extracted from the OIDC request object.
type: object
properties:
client_id:
description: |
The clientId that the caller claims to have.
At this stage, Heimdall has verified that the client id exists.
type: string
response_type:
type: string
scope:
type: string
request:
type: string
scopes:
description: |
The requested scope in the authorization request broken down into an array
type: array
items:
type: string
claims:
description: |
The requested claims in the authorization request.
type: object
additionalProperties: true
additionalProperties: true
claims:
type: object
status:
type: string
consentId:
type: string
description: An identifier for consent
deprecated: true
consentIdsList:
type: array
description: |
Consent Ids associated with 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 consider
that this array may have a single value.
items:
type: string
tpp:
$ref: "#/components/schemas/tpp"
AuthErrorResponse:
type: object
properties:
noRedirect:
type: boolean
error:
type: string
error_description:
type: string
interactionId:
type: string
tpp:
type: object
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.
required:
- clientId
- orgId
- softwareStatementId
- tppName
properties:
clientId:
type: string
description: The clientId for the TPP as issued by Ozone
orgId:
type: string
description: The organization id for the TPP
softwareStatementId:
type: string
description: The organization id for the TPP
tppName:
type: string
description: The name of the TPP
directoryRecord:
type: string
description: The latest copy of the TPP directory record if the TPP has registered with a directory
parameters:
interactionId:
name: interactionId
in: query
schema:
type: string
required: true
description: Identifier for the interaction
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT |
...