openapi: 3.0.3
info:
title: E-Ident API
version: "1.0"
description: |
The E-Ident identity broker services allows customers to access multiple
electronic ID services/schemes through one common interface.
E-Ident provides a single point of integration to several eIDs utilizing standard authentication protocols to exchange information about the end user to the customer. The service is mostly used to let end users log on to a customer’s web site or to gain information about a user used for other purposes than log on. The returned user information varies from the different eID providers, and it may include some of the following:
* Name
* Date of birth
* Social security number (SSN)
* Serial number or eID specific identifier
__E-Ident supports two authentication protocols for user identification__
* __OIDC (OpenID Connect) -__ OpenID Connect is an authentication layer built on top of OAuth 2.0. E-Ident supports the Authorization Code Flow, which is suitable for all types of clients including web applications, mobile apps, and JavaScript-based clients. After successful authentication, user information is provided in the form of a signed ID token, which is a secure JSON Web Token (JWT).
* __SAML (Security Assertion Markup Language) 1.1 -__ As an alternative to OIDC, E-Ident supports SAML 1.1. Upon successful authentication, the service returns a SAML assertion containing user identity attributes. The SAML protocol also supports Single Sign-On (SSO) and logout functionality.
__This specification documents the API for accessing E-Ident and manages the following resources__
* token endpoint - ID token retrieval
* userinfo endpoint - authenticated user info
* authorisation endpoint - the authentication request
* global logout service - logging out
__Terms and expressions__
* Merchant/customer - the client or customer using this API to manage orders
* eID - Electronic ID is a digital identity that allows to authenticate online and access service securely
* IDP - an Identity Provider is a service that authenticates customer and provides identity information
* Transaction - the process of authenticating a user with an IDP
* Transaction ID - a unique identifier assigned to a specific transaction which is used to track the transaction
* PKCE flow - The Proof Key for Code Exchange flow allows Single Page Application (SPA) and native apps to retrieve the ID token directly in a secure way without revealing the password and not through a backend call.
* CIBA flow - The Client Initiated Backchannel Authentication flow enables authentication sessions to be initiated and processed in a different channel than the browser through the E-Ident web UI.
* Binding Message - A message that establishes a secure connection between systems
A merchant identifier (MID) and a secret code are required to integrate with E-Ident APIs.
The identifier and the code can be received by using the [Contact us form](https://ingroupe.com/in-trust-services-support-contact-page/) to IN Groupe support.
To receive a dedicated setup, you need to be an E-Ident customer. To become a customer, [ Contact our sales department](https://ingroupe.com/in-trust-services-support-contact-page/)
[The OAuth 2.0 Authorization Framework, RFC 7636](https://tools.ietf.org/html/rfc7636)
contact:
url: https://doc.ingroupe.com/developer/e-ident
paths:
###############################################################
#
# Authorization server endpoints
#
/oidc/.well-known/openid-configuration:
get:
operationId: metadataEndpoint
summary: Get OpenID Provider configuration information
description: |
## Specification
Discovery endpoint used by OpenID Connect Relying Party to discover the End-User's OpenID Provider and obtain information needed to interact with it, including its OAuth 2.0 endpoint locations.
tags:
- Discovery
responses:
'200':
description: The OpenID Provider Metadata
content:
application/json:
schema:
$ref: '#/components/schemas/OpenIDProviderMetadataResponse'
/its/index.html:
get:
operationId: authorizeRedirect
summary: The authorization endpoint for the 'authorization_code' flow.
description: |
## Specification
This is the [Authorization Endpoint][RFC 6749 §3.1], used as part of
the [Authorization Code Grant][RFC 6749 §4.1], with the [PKCE
extension][RFC 7636 §4.3].
## Signed Request
E-Ident supports Signed Request Object (Signed JWT) in OIDC requests. Both request and request_uri parameters are supported as specified by the OIDC standard.
E-Ident will do a RSA signature verification to make sure that the Request Object is signed by the expected E-Ident customer by using a public key associated with the client_id.
The customer will need to provide IN Groupe with one of the following options:
* A URL to a JWKS endpoint where IN Groupe can look up a public key for signing purposes. It is optional to also provide a key id. Otherwise the first public key in the response from the endpoint will be used.
* The RSA key members and the key type in JSON format.
## PSD2 Implementation notes
For PSD2 TPPs, all clients must use the PKCE extension with the
SHA-256 code challenge method.
## Documentation notes
This endpoint is documented here mostly in order to document its
parameters.
The actual URLs of the authorization endpoints are documented on the
[OAuth 2 Endpoints] page on the developer portal.
tags:
- Auth request
parameters:
- $ref: '#/components/parameters/client_id'
- $ref: '#/components/parameters/redirect_uri'
- $ref: '#/components/parameters/scope'
- $ref: '#/components/parameters/response_type'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/nonce'
- $ref: '#/components/parameters/ui_locale'
- $ref: '#/components/parameters/display'
- $ref: '#/components/parameters/prompt'
- $ref: '#/components/parameters/max_age'
- $ref: '#/components/parameters/id_token_hint'
- $ref: '#/components/parameters/login_hint'
- $ref: '#/components/parameters/acr_values'
- $ref: '#/components/parameters/code_challenge'
- $ref: '#/components/parameters/code_challenge_method'
- $ref: '#/components/parameters/binding_message'
- $ref: '#/components/parameters/eident_context'
- $ref: '#/components/parameters/request'
- $ref: '#/components/parameters/request_uri'
responses:
'default':
description: |
A HTML content shown to a user agent to begin the OAuth 2 authorization
process. This endpoint will eventually redirect to the redirection
endpoint specified by the TPP, which will receive the `code` and
`state` parameters as specified by [RFC 6749 §4.1.2].
In case parameters are missing or wrong, an error page will be
shown. In case the `client_id` and the `redirect_uri` match, the
user will also be redirected to the redirection endpoint specified
by the TPP, with parameters `error` and `error_description` filled
as specified by [RFC 6749 §4.1.2.1].
content:
text/html: {}
/oidc/ciba.html:
post:
operationId: authorizeBackchannel
security:
- basicAuth: []
summary: The CIBA authorization endpoint.
description: |
## Specification
Standard authentication using OIDC relies on the user agent (user's browser) first access the OIDC provider to initiate the session. The response from the provider is a web UI that guides the user through the authentication sequence.
The Client Initiated Backchannel Authentication (CIBA) flow enables authentication sessions to be initiated and processed in a different channel than the browser through the E-Ident web UI.
tags:
- Auth request
parameters:
- $ref: '#/components/parameters/scope'
- $ref: '#/components/parameters/client_notification_token'
- $ref: '#/components/parameters/login_hint_token'
- $ref: '#/components/parameters/acr_values'
- $ref: '#/components/parameters/id_token_hint'
- $ref: '#/components/parameters/login_hint'
- $ref: '#/components/parameters/user_code'
- $ref: '#/components/parameters/binding_message'
- $ref: '#/components/parameters/requested_expiry'
responses:
'200':
description: Claims about the authenticated End-User
content:
application/jwt:
schema:
$ref: '#/components/schemas/CibaResponseJwt'
'400':
description: As per RFC authorisation server responds with 400 in case of error
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationErrorResponse'
example:
error: invalid_request
/oidc/token:
post:
operationId: tokenRetrieve
security:
- basicAuth: []
summary: Request Access Token
tags:
- Tokens
description: |
## Specification
Retrieve the ID token for the authorisation whose code has been issued. This is also used for CIBA flow.
The ID Token is a JSON Web Token (JWT) and is either signed or signed-then-encrypted. The default is signed.
The ID Token signature should be validated using the public key that is mentioned in the kid element in JWT header. The corresponding key can be looked up from E-Ident’s JWKS endpoint.
The ID Token is valid for 15 minutes. Successive token requests with the same authorization code (code) will result in error and invalidation of previously accessed tokens.
## ID Token Encryption
Customers can request IN Groupe to encrypt all ID Tokens. The ID Token will be encrypted using RSA-OAEP-256 and AES, as described by RFC 7516. JWE Compact serialization is used and the encryption is done after signing, which means that the customer needs to decrypt the ID Token before being able to validate the signature.
The customer will need to provide IN Groupe with one of the following options:
* A URL to a JWKS endpoint where IN Groupe can look up a public key for encryption purposes. It is optional to also provide a key id. Otherwise the first public key in the response from the endpoint will be used.
* The RSA key members and the key type in JSON format.
parameters:
- $ref: '#/components/parameters/grant_type'
- $ref: '#/components/parameters/code'
- $ref: '#/components/parameters/redirect_uri_token'
- $ref: '#/components/parameters/client_id_token'
- $ref: '#/components/parameters/code_verifier'
responses:
'200':
description: Authorization token (Bearer)
content:
application/json:
schema:
$ref: '#/components/schemas/IDTokenResponse'
example:
access_token: 3049076c-d365-4b05-9e76
token_type: Bearer
id_token: eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyfQo
expires_in: 3600
'400':
description: As per RFC authorisation server responds with 400 in case of error
content:
application/json:
schema:
$ref: '#/components/schemas/IDTokenErrorResponse'
example:
error: invalid_request
delete:
operationId: deleteToken
security:
- basicAuth: []
summary: Invalidate access token
tags:
- Tokens
responses:
'200':
description: Empty body with 200 code
'403':
description: Access Token already invalidated or not found
'500':
description: Internal server error
/oidc/userinfo:
get:
operationId: userInfoGet
security:
- bearerAuth: []
summary: Get claims about the authenticated End-User
description: |
## Specification
The UserInfo Endpoint is an OAuth 2.0 Protected Resource. It claims about the authenticated user, including some claims not available in the ID token. Accessing this endpoint requires an access token. This token is returned together with the ID token. The access token shouldn't be expired to get the authentication data. The endpoint response will be signed by default and encrypted optionally.
tags:
- Tokens
responses:
'400':
description: Invalid Request
'401':
description: Invalid Token
'200':
description: Claims about the authenticated End-User
content:
application/jwt:
schema:
$ref: '#/components/schemas/UserInfoJWT'
post:
operationId: userInfoPost
security:
- bearerAuth: []
summary: Get claims about the authenticated End-User
description: |
## Specification
The UserInfo Endpoint is an OAuth 2.0 Protected Resource. It claims about the authenticated user, including some claims not available in the ID token. Accessing this endpoint requires an access token. This token is returned together with the ID token. The access token shouldn't be expired to get the authentication data. The endpoint response will be signed by default and encrypted optionally.
tags:
- Tokens
responses:
'400':
description: Invalid Request
'401':
description: Invalid Token
'200':
description: Claims about the authenticated End-User
content:
application/jwt:
schema:
$ref: '#/components/schemas/UserInfoJWT'
/auth_files/fetch.html:
post:
operationId: authFilesFetch
security:
- basicAuth: []
summary: Auth-files endpoint
description: |
## Specification
This endpoint allows customers to fetch PDF or PNG files as documentation for an recent authentication through Passport Reader.
tags:
- Auth-files request
parameters:
- $ref: '#/components/parameters/tid'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
params:
type: object
required:
- type
properties:
type:
type: string
enum: [application/pdf, image/png]
description: MIME type of file to download
source:
type: string
enum: [document, selfie]
description: Required if type is image/png
pagesize:
type: string
enum: [a4, letter]
description: Optional if type is application/pdf
locale:
type: string
enum: [nb-NO, nn-NO, en-GB, da-DK, sv-SE, fi-FI, sv-FI]
user-password:
type: string
owner-password:
type: string
noprint:
type: boolean
noprinthq:
type: boolean
nocopy:
type: boolean
noedit:
type: boolean
noannotations:
type: boolean
nofillinforms:
type: boolean
noaccesscontent:
type: boolean
noassembledoc:
type: boolean
encrypt-metadata:
type: boolean
encryption-length:
type: integer
enum: [40, 48, 56, 64, 72, 80, 88, 96, 104, 112, 120, 128, 256]
default: 128
pdf-a-mode:
type: string
description: PDF/A profile compliance mode
generate-pades:
type: boolean
addendum:
type: object
additionalProperties:
type: string
description: Custom merchant-defined attributes
metadata:
type: object
properties:
dc:
type: object
additionalProperties:
type: string
description: Dublin Core properties
xmp:
type: object
additionalProperties:
type: string
description: XMP properties
pdf:
type: object
additionalProperties:
type: string
description: PDF-specific metadata
custom:
type: object
additionalProperties:
type: string
description: Custom metadata attributes
responses:
'200':
description: Auth file successfully fetched
content:
application/jwt:
schema:
$ref: '#/components/schemas/AuthFilesResponseJson'
'400':
description: Authorisation server responds with 400 in case of error
content:
application/json:
schema:
$ref: '#/components/schemas/AuthFilesErrorResponseJson'
###############################################################
#
# Merchant self service
#
# /register:
# /register/{client_id}:
# /register/{client_id}/renew_secret:
###############################################################
#
# Component schemas
#
components:
schemas:
OpenIDProviderMetadataResponse:
type: object
required:
[issuer, authorization_endpoint, jwks_uri, response_types_supported, subject_types_supported, id_token_signing_alg_values_supported, token_endpoint, backchannel_token_delivery_modes_supported, backchannel_authentication_endpoint, entity_statement_uri]
properties:
issuer:
type: string
description: |
REQUIRED. URL using the https scheme with no query or fragment component that the OP asserts as its Issuer Identifier
authorization_endpoint:
type: string
description: |
REQUIRED. URL of the OP's OAuth 2.0 Authorization Endpoint
token_endpoint:
type: string
description: |
URL of the OP's OAuth 2.0 Token Endpoint
userinfo_endpoint:
type: string
description: |
RECOMMENDED. URL of the OP's UserInfo Endpoint
jwks_uri:
type: string
description: |
REQUIRED. URL of the OP's JSON Web Key Set [JWK] document.
registration_endpoint:
type: string
description: |
RECOMMENDED. URL of the OP's Dynamic Client Registration Endpoint
scopes_supported:
type: array
items:
$ref: '#/components/schemas/ScopesEnum'
description: |
RECOMMENDED. JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports
example: [openid, profile]
response_types_supported:
type: array
items:
$ref: '#/components/schemas/ResponseTypeEnum'
description: |
REQUIRED. JSON array containing a list of the OAuth 2.0 response_type values that this OP supports
response_modes_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the OAuth 2.0 response_mode values that this OP supports
grant_types_supported:
type: array
items:
$ref: '#/components/schemas/GrantTypeEnum'
description: |
OPTIONAL. JSON array containing a list of the OAuth 2.0 Grant Type values that this OP supports
acr_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the Authentication Context Class References that this OP supports
subject_types_supported:
type: array
items:
$ref: '#/components/schemas/SubjectTypeEnum'
description: |
REQUIRED. JSON array containing a list of the Subject Identifier types that this OP supports
id_token_signing_alg_values_supported:
type: array
items:
$ref: '#/components/schemas/IdTokenSignAlgEnum'
description: |
REQUIRED. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT
id_token_encryption_alg_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for the ID Token to encode the Claims in a JWT
id_token_encryption_enc_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for the ID Token to encode the Claims in a JWT
userinfo_signing_alg_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT
userinfo_encryption_alg_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT
userinfo_encryption_enc_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT
request_object_signing_alg_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the OP for Request Objects
request_object_encryption_alg_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the JWE encryption algorithms (alg values) supported by the OP for Request Objects
request_object_encryption_enc_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the JWE encryption algorithms (enc values) supported by the OP for Request Objects
token_endpoint_auth_methods_supported:
type: array
items:
$ref: '#/components/schemas/TokenAuthMethodEnum'
description: |
OPTIONAL. JSON array containing a list of Client Authentication methods supported by this Token Endpoint
token_endpoint_auth_signing_alg_values_supported:
type: array
items:
$ref: '#/components/schemas/TokenSignAlgEnum'
description: |
OPTIONAL. JSON array containing a list of the JWS signing algorithms (alg values) supported by the Token Endpoint for the signature on the JWT
display_values_supported:
type: string
description: |
OPTIONAL. JSON array containing a list of the display parameter values that the OpenID Provider supports
claim_types_supported:
type: array
items:
$ref: '#/components/schemas/ClaimTypeEnum'
description: |
OPTIONAL. JSON array containing a list of the Claim Types that the OpenID Provider supports
claims_supported:
type: string
description: |
RECOMMENDED. JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for
service_documentation:
type: string
description: |
OPTIONAL. URL of a page containing human-readable information that developers might want or need to know when using the OpenID Provider
claims_locales_supported:
type: string
description: |
OPTIONAL. Languages and scripts supported for values in Claims being returned, represented as a JSON array of BCP47 [RFC5646] language tag values
ui_locales_supported:
type: array
items:
$ref: '#/components/schemas/LanguageCodesEnum'
description: |
OPTIONAL. Languages and scripts supported for the user interface, represented as a JSON array of BCP47 [RFC5646] language tag values
claims_parameter_supported:
type: boolean
description: |
OPTIONAL. Boolean value specifying whether the OP supports use of the claims parameter, with true indicating support. If omitted, the default value is false
request_parameter_supported:
type: boolean
description: |
OPTIONAL. Boolean value specifying whether the OP supports use of the request parameter, with true indicating support. If omitted, the default value is false
request_uri_parameter_supported:
type: boolean
description: |
OPTIONAL. Boolean value specifying whether the OP supports use of the request_uri parameter, with true indicating support. If omitted, the default value is true
require_request_uri_registration:
type: boolean
description: |
OPTIONAL. Boolean value specifying whether the OP requires any request_uri values used to be pre-registered using the request_uris registration parameter
op_policy_uri:
type: string
description: |
OPTIONAL. URL that the OpenID Provider provides to the person registering the Client to read about the OP's requirements on how the Relying Party can use the data provided by the OP
op_tos_uri:
type: boolean
description: |
OPTIONAL. URL that the OpenID Provider provides to the person registering the Client to read about OpenID Provider's terms of service
backchannel_token_delivery_modes_supported:
type: array
items :
$ref: '#/components/schemas/CIBADeliveryModesEnum'
description: |
REQUIRED. JSON array containing one or more of the following values-
backchannel_authentication_endpoint:
type: string
description: |
REQUIRED. URL of the OP's Backchannel Authentication Endpoint
entity_statement_uri:
type: string
description: |
REQUIRED. NOT AVAILABLE
IDTokenResponse:
type: object
required:
[access_token, token_type, id_token]
properties:
access_token:
type: string
description: The access token value.
token_type:
$ref: '#/components/schemas/TokenTypeEnum'
expires_in:
type: number
description: The lifetime of the access token, in seconds.
id_token:
type: string
format: jwt
description: A signed and/or encrypted Jwt containing ID token claims. The decoded payload matches the `IdTokenDef` type definition.
refresh_token:
type: string
description: The refresh token to use, for an `authorization_code` token request.
scope:
$ref: '#/components/schemas/ScopesEnum'
IDTokenErrorResponse:
type: object
required:
[error]
properties:
error:
$ref: '#/components/schemas/TokenErrorEnum'
error_description:
type: string
description: A human-readable error message that gives details about the error.
error_uri:
type: string
description: A URL that gives more information about the error.
AuthorizationErrorResponse:
type: object
required:
[error]
properties:
error:
$ref: '#/components/schemas/AuthorizationErrorEnum'
error_description:
type: string
description: A human-readable error message that gives details about the error.
error_uri:
type: string
description: A URL that gives more information about the error.
AuthFilesErrorResponseJson:
type: object
properties:
response-type:
type: string
description: Status of a response like VOID, FAIL, RETRY etc.
response-code:
type: string
description: Error code
response-message:
type: string
description: A human-readable error message that gives details about the error.
CibaResponseJwt:
type: object
required:
[auth_req_id, expires_in]
properties:
auth_req_id:
type: string
description: This is a unique identifier to identify the authentication request made by the Client.
expires_in:
type: number
description: A JSON number with a positive integer value indicating the expiration time of the `auth_req_id` in seconds since the authentication request was received.
interval:
type: number
description: A JSON number with a positive integer value indicating the minimum amount of time in seconds that the Client MUST wait between polling requests to the token endpoint.
AuthFilesResponseJson:
type: object
properties:
response-type:
type: string
enum: [DATA, PASS, FAIL]
description: Status of a response.
pdf:
type: string
description: The PDF as a base64 encoded string
png:
type: string
description: The PNG as a base64 encoded string.
content-type:
type: string
description: Content type of the response data (image/png, application/pdf).
content-format:
type: string
enum: [PDF, PADES]
description: Actual content format delivered.
content-source:
type: string
description: Source of the file in attribute png.
content-reason:
type: string
description: Explanation, if PDF signature was not applied.
MerchantIdentification:
type: string
description: |
The client ID assigned upon registration.
UserInfoJWT:
type: string
format: jwt
description: |
A signed and/or encrypted Jwt containing user claims. The decoded payload matches the `UserInfoResponseDef` type definition.
###############################################################
#
# Type defs
#
UserInfoResponseDef:
type: object
properties:
sub:
$ref: '#/components/schemas/SubClaimDef'
name:
type: string
given_name:
type: string
description: Given name(s) or first name(s) of the End-User
family_name:
type: string
description: Surname(s) or last name(s) of the End-User
middle_name:
type: string
description: Middle name(s) of the End-User
nickname:
type: string
preferred_username:
type: string
profile:
type: string
description: URL of the End-User's profile page
picture:
type: string
description: URL of the End-User's profile picture
website:
type: string
description: URL of the End-User's Web page or blog
email:
type: string
format: email
description: End-User's preferred e-mail address
email_verified:
type: boolean
description: User at the time the verification was performed
gender:
type: string
description: End-User's gender
birthdate:
type: string
description: |
End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format
zoneinfo:
type: string
description: String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone
locale:
type: string
description: End-User's locale, represented as a BCP47 [RFC5646] language tag
phone_number:
type: string
description: End-User's preferred telephone number
phone_number_verified:
type: boolean
description: User at the time the verification was performed
address:
$ref: '#/components/schemas/AddressClaimDef'
updated_at:
type: integer
description: Time the End-User's information was last updated
IdTokenDef:
type: object
required: [iss, sub, aud, exp, iat]
properties:
iss:
type: string
description: Issuer Identifier for the Issuer of the response.
sub:
$ref: '#/components/schemas/SubClaimDef'
aud:
$ref: '#/components/schemas/AudClaimDef'
exp:
$ref: '#/components/schemas/ExpClaimDef'
iat:
type: integer
format: int64
description: Time at which the JWT was issued.
auth_time:
type: integer
format: int64
description: Time when the End-User authentication occurred.
nonce:
type: string
description: |
String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
acr:
type: string
description: Authentication Context Class Reference.
amr:
$ref: '#/components/schemas/AmrClaimDef'
azp:
type: string
description: |
Authorized party - the party to which the ID Token was issued
name:
type: string
given_name:
type: string
description: Given name(s) or first name(s) of the End-User
family_name:
type: string
description: Surname(s) or last name(s) of the End-User
middle_name:
type: string
description: Middle name(s) of the End-User
nickname:
type: string
preferred_username:
type: string
profile:
type: string
description: URL of the End-User's profile page
picture:
type: string
description: URL of the End-User's profile picture
website:
type: string
description: URL of the End-User's Web page or blog
email:
type: string
format: email
description: End-User's preferred e-mail address
email_verified:
type: boolean
description: User at the time the verification was performed
gender:
type: string
description: End-User's gender
birthdate:
type: string
description: |
End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format
zoneinfo:
type: string
description: String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone
locale:
type: string
description: End-User's locale, represented as a BCP47 [RFC5646] language tag
phone_number:
type: string
description: End-User's preferred telephone number
phone_number_verified:
type: boolean
description: User at the time the verification was performed
address:
$ref: '#/components/schemas/AddressClaimDef'
updated_at:
type: integer
description: Time the End-User's information was last updated
AddressClaimDef:
type: object
description: End-User's preferred postal address
properties:
formatted:
type: string
description: Full mailing address formatted for display
street_address:
type: string
description: Street address portion of the address
locality:
type: string
description: City or locality
region:
type: string
description: State, province, or region
postal_code:
type: string
description: ZIP or postal code
country:
type: string
description: Country name
AudClaimDef:
oneOf:
- type: string
- type: array
items:
type: string
description: Audience that this ID Token is intended for.
ExpClaimDef:
type: integer
format: int64
description: |
Expiration time on or after which the ID Token MUST NOT be accepted by the RP when performing authentication with the OP.
SubClaimDef:
type: string
description: Subject - Identifier for the End-User at the Issuer
AmrClaimDef:
oneOf:
- type: string
- type: array
items:
type: string
description: Authentication Methods References.
RequestObjectDef:
type: object
properties:
iss:
$ref: '#/components/parameters/iss'
aud:
$ref: '#/components/parameters/aud'
response_type:
$ref: '#/components/parameters/response_type'
client_id:
$ref: '#/components/parameters/client_id'
redirect_uri:
$ref: '#/components/parameters/redirect_uri'
scope:
$ref: '#/components/parameters/scope'
state:
$ref: '#/components/parameters/state'
nonce:
$ref: '#/components/parameters/nonce'
max_age:
$ref: '#/components/parameters/max_age'
###############################################################
#
# Enumerations
#
ScopesEnum:
type: string
pattern: ^(openid|profile|email|phone|address|cert|ssn|organisation|offline_access|ageverify[0-9]{1,2})( (openid|profile|email|phone|address|cert|ssn|organisation|offline_access|ageverify[0-9]{1,2}))*$
description: >
Supported scopes:
- openid
- profile
- email
- phone
- address
- cert
- ssn
- organisation
- offline_access
- ageverify followed by 1 or 2 digits (e.g., ageverify18, ageverify99)
TokenTypeEnum:
type: string
enum:
- BEARER
LanguageCodesEnum:
type: string
enum:
- nb_NO
- en_GB
- da_DK
- sv_SE
- fi_FI
- sv_FI
- nn_NO
- et_EE
- lv_LV
- de_DE
- nl_NL
- fr_FR
DisplayTypesEnum:
type: string
enum:
- page
- popup
- touch
- wap
PromptEnum:
type: string
enum:
- none
- login
- consent
- select_account
AuthorizationErrorEnum:
type: string
enum:
- invalid_request
- invalid_client
- invalid_grant
- unauthorized_client
- unsupported_grant_type
- invalid_scope
TokenErrorEnum:
type: string
enum:
- invalid_request
- invalid_grant
- unsupported_grant_type
- invalid_scope
CIBADeliveryModesEnum:
type: string
enum:
- poll
- ping
- push
TokenSignAlgEnum :
type: string
enum :
- RS256
- ES256
TokenAuthMethodEnum :
type: string
enum :
- client_secret_post
- client_secret_basic
- client_secret_jwt
- private_key_jwt
GrantTypeEnum :
type : string
enum :
- authorization_code
- implicit
- urn:openid:params:grant-type:ciba
SubjectTypeEnum :
type : string
enum :
- public
- pairwise
ClaimTypeEnum :
type : string
enum :
- normal
- aggregated
- distributed
IdTokenSignAlgEnum:
type : string
enum :
- RS256
- ES256
ResponseTypeEnum :
type : string
enum :
- code
- code id_token
- id_token
- id_token token
###############################################################
#
# Parameters
#
parameters:
client_id:
in: query
name: client_id
description: |
The OAuth2 `client_id` assigned to the client when it was
registered.
required: true
schema:
$ref: '#/components/schemas/MerchantIdentification'
redirect_uri:
in: query
name: redirect_uri
description: |
The OAuth2 `redirect_uri`, which must be one of the
registered URIs for the client.
required: true
schema:
type: string
TARGET:
in: query
name: target
description: |
SAML merchant target.
required: false
schema:
type: string
scope:
in: query
name: scope
description: |
The OAuth2 `scope` on which the client requires access.
It is required because no default scope is positioned.
required: true
schema:
$ref: '#/components/schemas/ScopesEnum'
client_notification_token:
in: query
name: client_notification_token
description: |
REQUIRED if the Client is registered to use Ping or Push modes. It is a bearer token provided by the Client that will be used by the OpenID Provider to authenticate the callback request to the Client.
required: false
schema:
type: string
login_hint_token:
in: query
name: login_hint_token
description: |
A token containing information identifying the end-user for whom authentication is being requested.
required: false
schema:
type: string
user_code:
in: query
name: user_code
description: |
A secret code, such as a password or pin, that is known only to the user but verifiable by the OP.
required: false
schema:
type: string
response_type:
in: query
name: response_type
description: |
The OAuth2 `response_type`. Only the authorization code
workflow is supported.
required: true
schema:
type: string
enum:
- code
state:
in: query
name: state
description: |
The OAuth2 `state`, to be retransmitted in the query
string when redirecting to the TPP redirection endpoint. We have
made this parameter mandatory because its absence implies the
presence of a CSRF vulnerability for the TPP.
required: true
schema:
type: string
nonce:
in: query
name: nonce
description: |
String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the `nonce` values used to prevent attackers from guessing values.
required: false
schema:
type: string
ui_locale:
in: query
name: ui_locale
description: |
The ISO 639-2 code of the language in which the
authorization page will be displayed.
required: false
schema:
$ref: '#/components/schemas/LanguageCodesEnum'
display:
in: query
name: display
description: |
Display types for auth and consent UIs.
required: false
schema:
$ref: '#/components/schemas/DisplayTypesEnum'
prompt:
in: query
name: prompt
description: |
Space-delimited, case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent.
required: false
schema:
$ref: '#/components/schemas/PromptEnum'
max_age:
in: query
name: max_age
description: |
Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated by the OP. If the elapsed time is greater than this value, the OP MUST attempt to actively re-authenticate the End-User.
required: false
schema:
type: number
id_token_hint:
in: query
name: id_token_hint
description: |
ID Token previously issued by the Authorization Server being passed as a hint about the End-User's current or past authenticated session with the Client.
required: false
schema:
type: string
login_hint:
in: query
name: login_hint
description: |
Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary).
required: false
schema:
type: string
acr_values:
in: query
name: acr_values
description: |
Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference.
required: false
schema:
type: string
code_challenge:
in: query
name: code_challenge
description: |
The OAuth2 PKCE `code_challenge`. Its use is mandatory
for PSD2-related clients.
required: false
schema:
type: string
pattern: '[a-zA-Z0-9._~-]{43}'
code_challenge_method:
in: query
name: code_challenge_method
description: |
The OAuth2 PKCE `code_challenge_method`. Only the S256
method (hashing the `code_verifier` with SHA-256) is supported.
required: false
schema:
type: string
enum:
- S256
binding_message:
in: query
name: binding_message
description: |
A human-readable identifier or message intended to be displayed on both the consumption device and the authentication device to interlock them together for the transaction by way of a visual cue for the end-user. This can contain a text/json/base64 encoded value.
The following attributes can be provided if the JSON format is used:
* ntdr-doc-types:
A comma-separated list with I, P, D or V, for selecting the required documents for ID verification.
I - ID cards, P - Passport booklets, D - Driver's license, V - Viza/crew credentials.
* ntdr-app-doclist (type: boolean):
Flag indicating whether the document type selection page will be shown to the user.
* transactiontext:
This can have values in plain text or in markdown. It can accept maximum of 1500 base64 encoded characters.
* transactiontext_type:
This will accept only “text" or “markdown" value which is a type of value passed in transactiontext.
* operation:
Contains values "cancel" which is passed to cancel an ongoing transaction.
* auth_req_id:
ID of an ongoing transaction which needs to be cancelled
* requestType:
To identify the purpose of request. It supports Provisioning & Authentication
* appId:
Application ID of the user.
* bindingMessage:
Text to be displayed on the end user's device in text format
* userStatus:
Used only for provisioning. If not provided the user status will be set to "active".
required: false
schema:
type: string
requested_expiry:
in: query
name: requested_expiry
description: |
A positive integer allowing the client to request the expires_in value for the auth_req_id the server will return.
required: false
schema:
type: number
request:
in: query
name: request
description: |
This parameter enables OpenID Connect requests to be passed in a single, self-contained parameter and to be optionally signed and/or encrypted. The parameter value is a Request Object value, as specified in `RequestObjectDef`. It represents the request as a JWT whose Claims are the request parameters.
required: false
schema:
type: string
request_uri:
in: query
name: request_uri
description: |
This parameter enables OpenID Connect requests to be passed by reference, rather than by value. The request_uri value is a URL referencing a resource containing a Request Object value, which is a JWT containing the request parameters. This URL MUST use the https scheme unless the target Request Object is signed in a way that is verifiable by the OP.
required: false
schema:
type: string
iss:
in: query
name: iss
description: Issuer Identifier for the Issuer of the response.
required: false
schema:
type: string
aud:
in: query
name: aud
description: Audience that a token is intended for.
required: false
schema:
type: string
eident_context:
in: query
name: eident_context
description: Text to be displayed on the end user's device in JSON format (Base 64 encoded).
schema:
type: string
tid:
in: query
name: tid
description: Auth file identifier.
required: true
schema:
type: string
grant_type:
in: query
name: grant_type
description: Value MUST be set to "authorization_code" as per RFC
required: true
schema:
type: string
enum:
- authorization_code
code:
in: query
name: code
description: |
The authorization code obtained by the redirection
endpoint in the `code` query string parameter.
required: true
schema:
type: string
code_verifier:
in: query
name: code_verifier
description: |
The `code_verifier` to check the PKCE challenge.
required: false
schema:
type: string
redirect_uri_token:
in: query
name: redirect_uri
description: |
The OAuth2 `redirect_uri`, which must be one of the
registered URIs for the client.
required: false
schema:
type: string
client_id_token:
in: query
name: client_id
description: |
The OAuth2 `client_id` assigned to the client when it was
registered.
required: false
schema:
$ref: '#/components/schemas/MerchantIdentification'
###############################################################
#
# Security
#
# Define security schemes
securitySchemes:
basicAuth: # arbitrary name for the security scheme
type: http
scheme: basic
bearerAuth: # arbitrary name for the security scheme
type: http
scheme: bearer
bearerFormat: JWT # optional, arbitrary value for documentation purposes
servers:
- url: https://www.ident-preprod1.nets.eu
variables: {}
description: Preprod (customer test)
- url: https://www.e-ident.nets.eu
variables: {}
description: Production