From 4ebbdd21927be0b91f206697171efc740a9c5309 Mon Sep 17 00:00:00 2001 From: Peter Havekes Date: Tue, 12 Aug 2025 10:21:34 +0200 Subject: [PATCH 1/3] Add openapi specification of institution information request and response --- .../aa/aggregators/institution/openapi.json | 150 ++++++++++++++++++ .../aa/aggregators/institution/openapi.yaml | 102 ++++++++++++ 2 files changed, 252 insertions(+) create mode 100644 src/main/java/aa/aggregators/institution/openapi.json create mode 100644 src/main/java/aa/aggregators/institution/openapi.yaml diff --git a/src/main/java/aa/aggregators/institution/openapi.json b/src/main/java/aa/aggregators/institution/openapi.json new file mode 100644 index 0000000..3c24aba --- /dev/null +++ b/src/main/java/aa/aggregators/institution/openapi.json @@ -0,0 +1,150 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "Instelling Attributes API", + "version": "1.0.0", + "description": "API voor het opvragen van attributen op basis van een eduID." + }, + "servers": [ + { + "url": "https://instelling.tld/api" + } + ], + "paths": { + "/attributes/{eduid}": { + "get": { + "summary": "Haal attributen op voor een gebruiker", + "description": "Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID.", + "parameters": [ + { + "name": "eduid", + "in": "path", + "required": true, + "description": "Het eduID van de gebruiker (UUID-formaat).", + "schema": { + "type": "string", + "format": "uuid", + "example": "0000-1111-2222-3333" + } + } + ], + "responses": { + "200": { + "description": "Succesvolle respons met attributen.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserAttributes" + } + } + } + }, + "400": { + "description": "Ongeldige request, bijvoorbeeld verkeerd UUID-formaat.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "error": "Invalid eduID format" + } + } + } + }, + "404": { + "description": "Gebruiker niet gevonden voor het opgegeven eduID.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "error": "User not found" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "AttributeArray": { + "type": "array", + "items": { + "type": "string" + } + }, + "UserAttributes": { + "type": "object", + "properties": { + "given_name": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["John"] + }, + "family_name": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["Doe"] + }, + "name": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["Prof.dr. John Doe"] + }, + "email": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["john.doe@example.com"] + }, + "ou": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["Faculty of Science"] + }, + "schac_home_organization": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["university.nl"] + }, + "eduperson_scoped_affiliation": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["student@uniharderwijk.nl"] + }, + "uids": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["jdoe123"] + }, + "schac_personal_unique_code": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["S12345678"] + }, + "eduperson_principal_name": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["johndoe@studenthartingcollege.nl"] + }, + "eduperson_entitlement": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["urn:x-surfnet:surf.nl:surfdrive:quota:100"] + }, + "edumember_is_member_of": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["research-group"] + }, + "eckid": { + "$ref": "#/components/schemas/AttributeArray", + "example": ["eck123456"] + } + } + }, + "ErrorResponse": { + "type": "object", + "properties": { + "error": { + "type": "string", + "description": "Beschrijving van de foutmelding" + } + }, + "required": ["error"] + } + } + } +} + diff --git a/src/main/java/aa/aggregators/institution/openapi.yaml b/src/main/java/aa/aggregators/institution/openapi.yaml new file mode 100644 index 0000000..8da0867 --- /dev/null +++ b/src/main/java/aa/aggregators/institution/openapi.yaml @@ -0,0 +1,102 @@ +openapi: 3.0.3 +info: + title: Instelling Attributes API + version: 1.0.0 + description: | + API voor het opvragen van attributen op basis van een eduID. +servers: + - url: https://instelling.tld/api +paths: + /attributes/{eduid}: + get: + summary: Haal attributen op voor een gebruiker + description: | + Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID. + parameters: + - name: eduid + in: path + required: true + description: Het eduID van de gebruiker (UUID-formaat). + schema: + type: string + format: uuid + example: 0000-1111-2222-3333 + responses: + '200': + description: Succesvolle respons met attributen. + content: + application/json: + schema: + $ref: '#/components/schemas/UserAttributes' + '400': + description: Ongeldige request, bijvoorbeeld verkeerd UUID-formaat. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: "Invalid eduID format" + '404': + description: Gebruiker niet gevonden voor het opgegeven eduID. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: "User not found" +components: + schemas: + AttributeArray: + type: array + items: + type: string + UserAttributes: + type: object + properties: + given_name: + $ref: '#/components/schemas/AttributeArray' + example: ["John"] + family_name: + $ref: '#/components/schemas/AttributeArray' + example: ["Doe"] + name: + $ref: '#/components/schemas/AttributeArray' + example: ["Prof.dr. John Doe"] + email: + $ref: '#/components/schemas/AttributeArray' + example: ["john.doe@example.com"] + ou: + $ref: '#/components/schemas/AttributeArray' + example: ["Faculty of Science"] + schac_home_organization: + $ref: '#/components/schemas/AttributeArray' + example: ["university.nl"] + eduperson_scoped_affiliation: + $ref: '#/components/schemas/AttributeArray' + example: ["student@uniharderwijk.nl"] + uids: + $ref: '#/components/schemas/AttributeArray' + example: ["jdoe123"] + schac_personal_unique_code: + $ref: '#/components/schemas/AttributeArray' + example: ["S12345678"] + eduperson_principal_name: + $ref: '#/components/schemas/AttributeArray' + example: ["johndoe@studenthartingcollege.nl"] + eduperson_entitlement: + $ref: '#/components/schemas/AttributeArray' + example: ["urn:x-surfnet:surf.nl:surfdrive:quota:100"] + edumember_is_member_of: + $ref: '#/components/schemas/AttributeArray' + example: ["research-group"] + eckid: + $ref: '#/components/schemas/AttributeArray' + example: ["eck123456"] + ErrorResponse: + type: object + properties: + error: + type: string + description: Beschrijving van de foutmelding + required: + - error From 1f39e7670631a080b6f11b65c9b120d3dbc2f31d Mon Sep 17 00:00:00 2001 From: Peter Havekes Date: Tue, 12 Aug 2025 16:49:42 +0200 Subject: [PATCH 2/3] Add authentication information to openapi --- .../aa/aggregators/institution/openapi.json | 36 ++++++++++++-- .../aa/aggregators/institution/openapi.yaml | 48 +++++++------------ 2 files changed, 48 insertions(+), 36 deletions(-) diff --git a/src/main/java/aa/aggregators/institution/openapi.json b/src/main/java/aa/aggregators/institution/openapi.json index 3c24aba..3908b97 100644 --- a/src/main/java/aa/aggregators/institution/openapi.json +++ b/src/main/java/aa/aggregators/institution/openapi.json @@ -3,7 +3,7 @@ "info": { "title": "Instelling Attributes API", "version": "1.0.0", - "description": "API voor het opvragen van attributen op basis van een eduID." + "description": "API voor het opvragen van attributen op basis van een eduID. Authenticatie gebeurt via HTTP Basic Authentication." }, "servers": [ { @@ -14,7 +14,7 @@ "/attributes/{eduid}": { "get": { "summary": "Haal attributen op voor een gebruiker", - "description": "Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID.", + "description": "Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID. Vereist HTTP Basic Authentication.", "parameters": [ { "name": "eduid", @@ -28,6 +28,11 @@ } } ], + "security": [ + { + "basicAuth": [] + } + ], "responses": { "200": { "description": "Succesvolle respons met attributen.", @@ -64,12 +69,31 @@ } } } + }, + "401": { + "description": "Authenticatie vereist of ongeldig.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "error": "Unauthorized" + } + } + } } } } } }, "components": { + "securitySchemes": { + "basicAuth": { + "type": "http", + "scheme": "basic" + } + }, "schemas": { "AttributeArray": { "type": "array", @@ -145,6 +169,10 @@ "required": ["error"] } } - } + }, + "security": [ + { + "basicAuth": [] + } + ] } - diff --git a/src/main/java/aa/aggregators/institution/openapi.yaml b/src/main/java/aa/aggregators/institution/openapi.yaml index 8da0867..160b193 100644 --- a/src/main/java/aa/aggregators/institution/openapi.yaml +++ b/src/main/java/aa/aggregators/institution/openapi.yaml @@ -4,6 +4,7 @@ info: version: 1.0.0 description: | API voor het opvragen van attributen op basis van een eduID. + Authenticatie gebeurt via HTTP Basic Authentication. servers: - url: https://instelling.tld/api paths: @@ -12,6 +13,7 @@ paths: summary: Haal attributen op voor een gebruiker description: | Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID. + Vereist HTTP Basic Authentication. parameters: - name: eduid in: path @@ -21,6 +23,8 @@ paths: type: string format: uuid example: 0000-1111-2222-3333 + security: + - basicAuth: [] responses: '200': description: Succesvolle respons met attributen. @@ -44,7 +48,19 @@ paths: $ref: '#/components/schemas/ErrorResponse' example: error: "User not found" + '401': + description: Authenticatie vereist of ongeldig. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: "Unauthorized" components: + securitySchemes: + basicAuth: + type: http + scheme: basic schemas: AttributeArray: type: array @@ -68,35 +84,3 @@ components: ou: $ref: '#/components/schemas/AttributeArray' example: ["Faculty of Science"] - schac_home_organization: - $ref: '#/components/schemas/AttributeArray' - example: ["university.nl"] - eduperson_scoped_affiliation: - $ref: '#/components/schemas/AttributeArray' - example: ["student@uniharderwijk.nl"] - uids: - $ref: '#/components/schemas/AttributeArray' - example: ["jdoe123"] - schac_personal_unique_code: - $ref: '#/components/schemas/AttributeArray' - example: ["S12345678"] - eduperson_principal_name: - $ref: '#/components/schemas/AttributeArray' - example: ["johndoe@studenthartingcollege.nl"] - eduperson_entitlement: - $ref: '#/components/schemas/AttributeArray' - example: ["urn:x-surfnet:surf.nl:surfdrive:quota:100"] - edumember_is_member_of: - $ref: '#/components/schemas/AttributeArray' - example: ["research-group"] - eckid: - $ref: '#/components/schemas/AttributeArray' - example: ["eck123456"] - ErrorResponse: - type: object - properties: - error: - type: string - description: Beschrijving van de foutmelding - required: - - error From 38d770380bcccc0977aa0bf02f530c4105e68e56 Mon Sep 17 00:00:00 2001 From: Peter Havekes Date: Thu, 14 Aug 2025 16:19:40 +0200 Subject: [PATCH 3/3] Update openapi spec --- .../aa/aggregators/institution/openapi.json | 23 ++++++-- .../aa/aggregators/institution/openapi.yaml | 52 ++++++++++++++++++- 2 files changed, 69 insertions(+), 6 deletions(-) diff --git a/src/main/java/aa/aggregators/institution/openapi.json b/src/main/java/aa/aggregators/institution/openapi.json index 3908b97..37c9093 100644 --- a/src/main/java/aa/aggregators/institution/openapi.json +++ b/src/main/java/aa/aggregators/institution/openapi.json @@ -3,18 +3,19 @@ "info": { "title": "Instelling Attributes API", "version": "1.0.0", - "description": "API voor het opvragen van attributen op basis van een eduID. Authenticatie gebeurt via HTTP Basic Authentication." + "description": "API voor het opvragen van attributen op basis van een eduID.\nAuthenticatie gebeurt via HTTP Basic Authentication.\n**Let op:** deze API mag uitsluitend via een beveiligde HTTPS-verbinding worden aangeroepen." }, "servers": [ { - "url": "https://instelling.tld/api" + "url": "https://instelling.tld/api", + "description": "Productieomgeving (alleen HTTPS toegestaan)" } ], "paths": { "/attributes/{eduid}": { "get": { "summary": "Haal attributen op voor een gebruiker", - "description": "Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID. Vereist HTTP Basic Authentication.", + "description": "Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID.\nAlle velden in de response zijn optioneel.\nVereist HTTP Basic Authentication en HTTPS.", "parameters": [ { "name": "eduid", @@ -35,7 +36,7 @@ ], "responses": { "200": { - "description": "Succesvolle respons met attributen.", + "description": "Succesvolle respons met attributen (alle velden optioneel).", "content": { "application/json": { "schema": { @@ -82,6 +83,19 @@ } } } + }, + "500": { + "description": "Interne serverfout.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + }, + "example": { + "error": "Internal server error" + } + } + } } } } @@ -103,6 +117,7 @@ }, "UserAttributes": { "type": "object", + "description": "Bevat alle mogelijke attributen van een gebruiker. Alle velden zijn optioneel; afwezigheid betekent dat het attribuut niet bekend is.", "properties": { "given_name": { "$ref": "#/components/schemas/AttributeArray", diff --git a/src/main/java/aa/aggregators/institution/openapi.yaml b/src/main/java/aa/aggregators/institution/openapi.yaml index 160b193..9c9aa21 100644 --- a/src/main/java/aa/aggregators/institution/openapi.yaml +++ b/src/main/java/aa/aggregators/institution/openapi.yaml @@ -5,15 +5,18 @@ info: description: | API voor het opvragen van attributen op basis van een eduID. Authenticatie gebeurt via HTTP Basic Authentication. + **Let op:** deze API mag uitsluitend via een beveiligde HTTPS-verbinding worden aangeroepen. servers: - url: https://instelling.tld/api + description: Productieomgeving (alleen HTTPS toegestaan) paths: /attributes/{eduid}: get: summary: Haal attributen op voor een gebruiker description: | Retourneert de attributen die gekoppeld zijn aan het opgegeven eduID. - Vereist HTTP Basic Authentication. + Alle velden in de response zijn optioneel. + Vereist HTTP Basic Authentication en HTTPS. parameters: - name: eduid in: path @@ -27,7 +30,7 @@ paths: - basicAuth: [] responses: '200': - description: Succesvolle respons met attributen. + description: Succesvolle respons met attributen (alle velden optioneel). content: application/json: schema: @@ -56,6 +59,14 @@ paths: $ref: '#/components/schemas/ErrorResponse' example: error: "Unauthorized" + '500': + description: Interne serverfout. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + error: "Internal server error" components: securitySchemes: basicAuth: @@ -68,6 +79,9 @@ components: type: string UserAttributes: type: object + description: | + Bevat alle mogelijke attributen van een gebruiker. + Alle velden zijn optioneel; afwezigheid betekent dat het attribuut niet bekend is. properties: given_name: $ref: '#/components/schemas/AttributeArray' @@ -84,3 +98,37 @@ components: ou: $ref: '#/components/schemas/AttributeArray' example: ["Faculty of Science"] + schac_home_organization: + $ref: '#/components/schemas/AttributeArray' + example: ["university.nl"] + eduperson_scoped_affiliation: + $ref: '#/components/schemas/AttributeArray' + example: ["student@uniharderwijk.nl"] + uids: + $ref: '#/components/schemas/AttributeArray' + example: ["jdoe123"] + schac_personal_unique_code: + $ref: '#/components/schemas/AttributeArray' + example: ["S12345678"] + eduperson_principal_name: + $ref: '#/components/schemas/AttributeArray' + example: ["johndoe@studenthartingcollege.nl"] + eduperson_entitlement: + $ref: '#/components/schemas/AttributeArray' + example: ["urn:x-surfnet:surf.nl:surfdrive:quota:100"] + edumember_is_member_of: + $ref: '#/components/schemas/AttributeArray' + example: ["research-group"] + eckid: + $ref: '#/components/schemas/AttributeArray' + example: ["eck123456"] + ErrorResponse: + type: object + properties: + error: + type: string + description: Beschrijving van de foutmelding + required: + - error +security: + - basicAuth: []