KNF:ARP service: verschil tussen versies
Naar navigatie springen
Naar zoeken springen
| (2 tussenliggende versies door 2 gebruikers niet weergegeven) | |||
| Regel 2: | Regel 2: | ||
Door middel van een Attribute Release Policy (ARP) bepaalt een onderwijsinstelling welke attributen (of persoonsgegevens) van haar gebruikers worden doorgegeven aan een Service Provider. Wanneer de configuratie van de ARP onjuist is kan dit ertoe leiden tot verstoring in de toegang tot digitale leermiddelen. De ARP service kan gebruikt worden om de actuele ARP configuratie op te vragen. |
Door middel van een Attribute Release Policy (ARP) bepaalt een onderwijsinstelling welke attributen (of persoonsgegevens) van haar gebruikers worden doorgegeven aan een Service Provider. Wanneer de configuratie van de ARP onjuist is kan dit ertoe leiden tot verstoring in de toegang tot digitale leermiddelen. De ARP service kan gebruikt worden om de actuele ARP configuratie op te vragen. |
||
| − | {{Info|Voor het gebruik van de ARP service is een API key nodig. Deze kan worden aangevraagd bij [mailto: |
+ | {{Info|Voor het gebruik van de ARP service is een API key nodig. Deze kan worden aangevraagd bij [mailto:implementaties@kennisnet.nl Kennisnet]}} |
De URL voor de ARP service is: https://arpservice.entree.kennisnet.nl |
De URL voor de ARP service is: https://arpservice.entree.kennisnet.nl |
||
De ARP service kent vier operaties: |
De ARP service kent vier operaties: |
||
| − | # Een lijst met alle scholen opvragen: ''/ |
+ | # Een lijst met alle scholen opvragen: ''/v2/arp/school-list'' |
| − | # Een lijst met alle Service Providers opvragen: ''/ |
+ | # Een lijst met alle Service Providers opvragen: ''/v2/arp/sp-list'' |
| − | # ARP configuratie voor een school – SP combinatie opvragen: ''/ |
+ | # ARP configuratie voor een school – SP combinatie opvragen: ''/v2/arp/school/{brin}/sp/{organisationCode}'' |
| − | # Als Service Provider de eigen ARP configuratie opvragen: ''/v1/arp/sp-config'' |
||
| + | ==Technisch documentatie == |
||
| − | De technisch documentatie van de API van de ARP service is te vinden op: https://arpservice.entree.kennisnet.nl/swagger-ui/index.html |
||
| + | De Swagger documentatie voor de v2 API is te vinden op: https://arpservice.entree.kennisnet.nl/swagger-ui/index.html?urls.primaryName=ARP%20V2%20(new%20platform) |
||
| + | De v2 API is reeds beschikbaar sinds juli 2022 en deze release bevat geen wijzigingen voor de v2 API. |
||
| − | ==Alle onderwijsinstellingen opvragen== |
||
| − | Voor het opvragen van de configuratie voor een specifieke onderwijsinstelling - Service Provider configuratie kan gebruik gemaakt worden van het BRIN nummer van de instelling. |
||
| − | Met behulp van de ''school-list'' operatie kunnen alle BRIN nummers die binnen Entree Federatie bekend zijn opgevraagd worden. |
||
| − | |||
| − | '''Operatie:''' https://arpservice.entree.kennisnet.nl/v1/arp/school-list |
||
| − | |||
| − | '''Antwoord:''' |
||
| − | <syntaxhighlight lang="json"> |
||
| − | [ |
||
| − | { |
||
| − | "brin": "01JO", |
||
| − | "friendlyName": "Stichting Koninklijke Auris Groep" |
||
| − | }, |
||
| − | { |
||
| − | "brin": "14CR", |
||
| − | "friendlyName": "Julianaschool" |
||
| − | }, |
||
| − | { |
||
| − | "brin": "00NT03", |
||
| − | "friendlyName": "Prof. Dr. Leo Kannercollege" |
||
| − | }, |
||
| − | { |
||
| − | "brin": "25PN01", |
||
| − | "friendlyName": "ROC Nijmegen VAVO" |
||
| − | }, |
||
| − | { |
||
| − | "brin": "02CI02", |
||
| − | "friendlyName": "Insula College" |
||
| − | }, |
||
| − | { |
||
| − | "brin": "17VS02", |
||
| − | "friendlyName": "Greijdanus Enschede" |
||
| − | }, |
||
| − | … |
||
| − | ] |
||
| − | </syntaxhighlight> |
||
| − | |||
| − | ==Alle Service Providers opvragen== |
||
| − | Voor het opvragen van de configuratie voor een specifieke onderwijsinstelling - Service Provider configuratie kan gebruik gemaakt worden van de organisationCode van de Service Provider. |
||
| − | Met behulp van de ''sp-list'' operatie kunnen alle organisationCode die binnen Entree Federatie bekend zijn opgevraagd worden. |
||
| − | |||
| − | '''Operatie:''' https://arpservice.entree.kennisnet.nl/v1/arp/sp-list |
||
| − | |||
| − | '''Antwoord:''' |
||
| − | <syntaxhighlight lang="json"> |
||
| − | [ |
||
| − | { |
||
| − | "organisationCode": "EXPLR", |
||
| − | "friendlyName": "Explor Onderwijs" |
||
| − | }, |
||
| − | { |
||
| − | "organisationCode": "VMBWI", |
||
| − | "friendlyName": "VmboBWI" |
||
| − | }, |
||
| − | { |
||
| − | "organisationCode": "XEBIC", |
||
| − | "friendlyName": "OnStage" |
||
| − | }, |
||
| − | { |
||
| − | "organisationCode": "VOCON", |
||
| − | "friendlyName": "VO-Content" |
||
| − | }, |
||
| − | { |
||
| − | "organisationCode": "TOEG", |
||
| − | "friendlyName": "Toegang.org" |
||
| − | }, |
||
| − | { |
||
| − | "organisationCode": "KUNSKA", |
||
| − | "friendlyName": "Kunskapsskolan" |
||
| − | }, |
||
| − | … |
||
| − | ] |
||
| − | </syntaxhighlight> |
||
| − | |||
| − | ==Onderwijsinstelling - Service Provider ARP opvragen== |
||
| − | Voor het opvragen van de configuratie voor een specifieke onderwijsinstelling - Service Provider ARP configuratie moet het BRIN nummer van de onderwijsinstelling en de organisationCode van de Service Provider worden opgegeven. |
||
| − | * Bij ''transfer: true'' wordt het attribuut doorgegeven aan de Service Provider |
||
| − | * Bij ''transfer: false'' wordt het attribuut niet doorgegeven aan de Service Provider |
||
| − | |||
| − | '''Operatie:''' https://arpservice.entree.kennisnet.nl/v1/arp/school/{brin}/sp/{organisationCode} |
||
| − | |||
| − | '''Antwoord:''' |
||
| − | <syntaxhighlight lang="json"> |
||
| − | [ |
||
| − | { |
||
| − | "serviceProvider": { |
||
| − | "organisationCode": "KRULLE", |
||
| − | "friendlyName": "Uitgeverij Krullevaar" |
||
| − | }, |
||
| − | "school": { |
||
| − | "brin": "20MG", |
||
| − | "friendlyName": "Musopia Lyceum" |
||
| − | }, |
||
| − | "identityProvider": { |
||
| − | "organisationCode": "xZmZzy", |
||
| − | "friendlyName": "Het Computergebouw IdP" |
||
| − | }, |
||
| − | "attributes": [ |
||
| − | { |
||
| − | "name": "nlEduPersonCohort", |
||
| − | "friendlyName": "Startjaar", |
||
| − | "transfer": false |
||
| − | }, |
||
| − | { |
||
| − | "name": "nlEduPersonDepartment", |
||
| − | "friendlyName": "Afdeling of sector", |
||
| − | "transfer": true |
||
| − | }, |
||
| − | { |
||
| − | "name": "eckId", |
||
| − | "friendlyName": "ECK ID", |
||
| − | "transfer": true |
||
| − | } |
||
| − | ] |
||
| − | } |
||
| − | ] |
||
| − | </syntaxhighlight> |
||
| − | |||
| − | ==ARP configuratie van een Service Provider== |
||
| − | Wanneer een partij als Service Provider aangesloten is op Entree Federatie dan kan deze de eigen ARP configuratie opvragen. |
||
| − | De door Kennisnet verstrekte API key is dan gekoppeld aan de specifieke Service Provider. |
||
| − | |||
| − | '''Operatie:''' https://arpservice.entree.kennisnet.nl/v1/arp/sp-config |
||
| − | |||
| − | '''Antwoord:''' |
||
| − | <syntaxhighlight lang="json"> |
||
| − | { |
||
| − | "serviceProvider": { |
||
| − | "organisationCode": "KRULLE", |
||
| − | "friendlyName": "Uitgeverij Krullevaar" |
||
| − | }, |
||
| − | |||
| − | "attributeReleasePolicy": [ |
||
| − | { |
||
| − | "school": { |
||
| − | "brin": "20MG", |
||
| − | "friendlyName": "Musopia Lyceum" |
||
| − | }, |
||
| − | "identityProvider": { |
||
| − | "organisationCode": "xZmZzy", |
||
| − | "friendlyName": "Het Computergebouw IdP" |
||
| − | }, |
||
| − | "attributes": [ |
||
| − | { |
||
| − | "name": "nlEduPersonCohort", |
||
| − | "friendlyName": "Startjaar", |
||
| − | "transfer": false |
||
| − | }, |
||
| − | { |
||
| − | "name": "nlEduPersonDepartment", |
||
| − | "friendlyName": "Afdeling of sector", |
||
| − | "transfer": true |
||
| − | }, |
||
| − | { |
||
| − | "name": "eckId", |
||
| − | "friendlyName": "ECK ID", |
||
| − | "transfer": true |
||
| − | } |
||
| − | ] |
||
| − | |||
| − | }, |
||
| − | … |
||
| − | ] |
||
| − | } |
||
| − | </syntaxhighlight> |
||
==Foutmeldingen== |
==Foutmeldingen== |
||
| Regel 193: | Regel 29: | ||
"error": "Forbidden", |
"error": "Forbidden", |
||
"message": "403 Forbidden", |
"message": "403 Forbidden", |
||
| − | "path": "/ |
+ | "path": "/v2/arp/school-list" |
} |
} |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
| Regel 207: | Regel 43: | ||
"error": "Bad Request", |
"error": "Bad Request", |
||
"message": "ARP configuration unavailable for school-Service Provider combination", |
"message": "ARP configuration unavailable for school-Service Provider combination", |
||
| − | "path": "/ |
+ | "path": "/v2/arp/school/20MG/sp/abcxyz" |
| − | } |
||
| − | </syntaxhighlight> |
||
| − | |||
| − | ===Service Provider configuratie niet beschikbaar=== |
||
| − | Foutmelding wanneer een Service Provider configuratie wordt opgevraagd, met een API key die niet aan een Service Provider gekoppeld is. |
||
| − | |||
| − | '''Antwoord:''' |
||
| − | <syntaxhighlight lang="json"> |
||
| − | { |
||
| − | "timestamp": "2021-02-22T16:47:07.283+0000", |
||
| − | "status": 400, |
||
| − | "error": "Bad Request", |
||
| − | "message": "ARP configuration unavailable for organisation", |
||
| − | "path": "/v1/arp/sp-config" |
||
} |
} |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
| Regel 235: | Regel 57: | ||
"error": "Internal Server Error", |
"error": "Internal Server Error", |
||
"message": "500 INTERNAL SERVER ERROR", |
"message": "500 INTERNAL SERVER ERROR", |
||
| − | "path": "/ |
+ | "path": "/v2/arp/school-list" |
} |
} |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
Huidige versie van 12 jan 2024 om 14:46
Inleiding
Door middel van een Attribute Release Policy (ARP) bepaalt een onderwijsinstelling welke attributen (of persoonsgegevens) van haar gebruikers worden doorgegeven aan een Service Provider. Wanneer de configuratie van de ARP onjuist is kan dit ertoe leiden tot verstoring in de toegang tot digitale leermiddelen. De ARP service kan gebruikt worden om de actuele ARP configuratie op te vragen.
|
Voor het gebruik van de ARP service is een API key nodig. Deze kan worden aangevraagd bij Kennisnet |
De URL voor de ARP service is: https://arpservice.entree.kennisnet.nl
De ARP service kent vier operaties:
- Een lijst met alle scholen opvragen: /v2/arp/school-list
- Een lijst met alle Service Providers opvragen: /v2/arp/sp-list
- ARP configuratie voor een school – SP combinatie opvragen: /v2/arp/school/{brin}/sp/{organisationCode}
Technisch documentatie
De Swagger documentatie voor de v2 API is te vinden op: https://arpservice.entree.kennisnet.nl/swagger-ui/index.html?urls.primaryName=ARP%20V2%20(new%20platform)
De v2 API is reeds beschikbaar sinds juli 2022 en deze release bevat geen wijzigingen voor de v2 API.
Foutmeldingen
De ARP service kan de volgende antwoorden geven op foutieve aanvragen:
Ongeldige API key
Foutmelding wanneer de gebruikte API key niet geldig is (geldt voor alle operaties)
Antwoord:
{
"timestamp": "2021-02-22T16:56:13.696+0000",
"status": 403,
"error": "Forbidden",
"message": "403 Forbidden",
"path": "/v2/arp/school-list"
}
Geen ARP configuratie bekend voor onderwijsinstelling en Service Provider
Foutmelding wanneer er geen ARP configuratie bekend is voor de combinatie van het BRIN nummer en de organisatieCode.
Antwoord:
{
"timestamp": "2021-02-22T15:48:12.902+0000",
"status": 400,
"error": "Bad Request",
"message": "ARP configuration unavailable for school-Service Provider combination",
"path": "/v2/arp/school/20MG/sp/abcxyz"
}
Interne server foutmelding ARP service
Foutmelding wanneer de ARP service een interne fout genereert (geldt voor alle operaties)
Antwoord:
{
"timestamp": "2021-02-22T17:04:55.481+0000",
"status": 500,
"error": "Internal Server Error",
"message": "500 INTERNAL SERVER ERROR",
"path": "/v2/arp/school-list"
}