The information we need:
General
- Name of the product
- Short description
- Usecases you want to treat
- Domain (or Domain-Pattern)
e.g. www.yourserver.com or www.*.(server1|server2).com - Restrictions for specific countries, regions or schools
For UI-Integration
- Redirect-Path: e.g. /untis
Must match with the REDIRECT_URL you send during the OAuth-Authentication! - Logout-Path: e.g. /logout
Will be called during the logout in WebUntis. - Optional Default-Values per User-Role
- Role (e.g. Admin, Student, Teacher, …)
- Name of the Menuentry (e.g. “Your Application”)
- Open in new Tab or integrated as an iFrame
- Different Redirect-pathes for each role are possible
- Optional Icon with these specifications:
- Size: 24x24px
- Color: #919DA6
- File format: png and svg
For API-Integration:
- Which APIs do you need?
We need to know, so that your platform application gets the correct permissions. - Optional: Credential-Path: e.g. /credentials
To transfer the platform credentials (secret, password, …) automatically, you must provide the following API. Otherwise, the school-administrator must copy the credentials and add them to your application manually and therefore you must provide a specific user interface.
Credenials API
|
POST |
JSON string with the data, for example: { |
Headers used to verify WU identity: Authorization - base64 encoded signature
|
Example HTTP request:
POST {partner.credentials.api} HTTP/1.1
Host: api.webuntis.integration.com
Content-Type: application/json; charset=utf-8
Content-Length: length
Connection: Keep-Alive
Authorization: zGPyG3bdqDbfJLk3s8jlRcbpreaCPhTJDywgh1JdqQYie5Aus0bzV/PjuFml1j+7B/6bEKI4xY+dh71dDJyvQWBkeS0DRxY883TPkvfMnfVr6vucTVjph5AARA9YXQw3OfGA5oDp9VXmBI22f4TFvanEWTqo5KD6pBM9FE+FUgEzDqXnB9FOogJ5xrfa8f0iU6Si3V0W3J20rIO71jf4V8Hvj9a9vs1p50ldi63SWeNAwO2wH+rxZXVtZ6RJqWkp720wgwIacfMezaw6lI0dodp0uDQnCmxarT07M4BbsvRciabe4tDJVuKd0JIpos4VargBtBPpgfXbPxWlSF6cTQ==
Algorithm: SHA256withRSA
{
"tenantId":"x",
"schoolName":"x",
"clientId":"x",
"secret":"x",
"password":"x",
"host": "x"
}
How can you verify WU identity:
By using public key provided by WU team and the signature in the headers.
How to do in PHP:
How to do in JAVA:
- API:
@PostMapping("/credentials")
public ResponseEntity<?> getAll(@RequestBody String request,
@RequestHeader("Authorization") String requestSignature,
@RequestHeader("Algorithm") String algorithm) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException, InvalidKeySpecException, JsonProcessingException, SignatureException { -
Verify signature:
// verify signatures using public key
byte[] decoded = Base64.getDecoder().decode(publicKeyString.getBytes());
X509EncodedKeySpec spec = new X509EncodedKeySpec(decoded);
KeyFactory kf = KeyFactory.getInstance("RSA");
PublicKey publicKey = kf.generatePublic(spec);
Signature signature = Signature.getInstance(algorithm);
signature.initVerify(publicKey);
signature.update(request);
// Signature in the header is BASE64 encoded
byte[] decodedSignature = Base64.getDecoder().decode(requestSignature.getBytes(StandardCharsets.UTF_8));
if (!signature.verify(decodedSignature)) {
throw new RestClientException("Invalid signature");
}
ObjectMapper mapper = new ObjectMapper();
PlatformCredentialsDto platformCredentialsDto = mapper.readValue(new String(decryptedRequest), PlatformCredentialsDto.class);
System.out.println(platformCredentialsDto.getTenantId());
System.out.println(platformCredentialsDto.getSecret());
System.out.println(platformCredentialsDto.getSchoolName());
System.out.println(platformCredentialsDto.getPassword());
System.out.println(platformCredentialsDto.getClientId());