openapi: 3.0.1
servers:
- url: https://{server}/v2024.07
description: Headless Heimdall APIs
variables:
server:
default: hh.*
description: The server that the API is hosted on.
info:
title: Headless Heimdall APIs
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 ASPSP at the end of their authorization journeys.
Headless Heimdall provides an API interface to an OIDC Authorization Server.
The interface allows for an ASPSP to develop the user interface for PSUs 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.
The interface consists of end-points:
- The __Headless Authorization End-point__ `GET /auth` should be called by the ASPSP 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
ASPSP to notify Heimdall that an interaction has completed successfully.
- The __Failure End-point__ `POST /auth/:interactionId/doFail` should be called by the ASPSP
to notify Heimdall that the interaction has failed.
version: Version 2.2 Release 26.4
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 ASPSP 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 an identifier for 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 ASPSP 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 302 redirect. The ASPSP 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 ASPSPs 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 ASPSP.
- `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 ASPSP 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.
### Parameters
OAS3 does not have a way to indicate a flexible set of query parameters.
When calling this API, the ASPSP 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 ASPSP should continue with the next stages of the interaction, keeping track of the
returned interactionId.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthSuccessResponse'
302:
description: |
This indicates that the parameters were not successfully verified.
However, there were no indications that the request originated from an invalid client.
The ASPSP should respond to the PSU 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 ASPSP should render an error page.
The ASPSP __must not__ redirect back to the TPP.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthErrorResponse'
security:
- bearerAuth: []
/auth/:interactionId/doConfirm:
post:
tags:
- headless-heimdall
summary: Ends an authorisation interaction with a success response
description: |
The Confirmation End-point should be called by the ASPSP 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 ASPSP 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 302 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.
"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.
"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.
additionalProperties: true
parameters:
- $ref: '#/components/parameters/interactionId'
responses:
302:
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 UI Provider must redirect the resource owner to the redirect uri.
security:
- bearerAuth: []
/auth/:interactionId/doFail:
post:
tags:
- headless-heimdall
summary: Ends an authorisation interaction with a failure response
description: |
The failure End-point should be called by the ASPSP 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 ASPSP can specify the `error` and `error_description` as x-www-form-urlencoded parameters.
Heimdall returns a 302 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:
302:
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 UI Provider 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.
If the authorization request is for the UK OBIE APIs, then the
property `id_token.openbanking_intent_id` indicates the consent to be authorised.
type: object
properties:
id_token:
type: object
properties:
openbanking_intent_id:
type: object
properties:
value:
type: string
additionalProperties: true
claims:
type: object
status:
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.
properties:
clientId:
type: string
orgId:
type: string
softwareStatementId:
type: string
directoryRecord:
type: object
additionalProperties: true
AuthErrorResponse:
type: object
properties:
noRedirect:
type: boolean
error:
type: string
error_description:
type: string
interactionId:
type: string
parameters:
interactionId:
name: interactionId
in: query
schema:
type: string
required: true
description: Identifier for the interaction | 