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: Different 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 (e.g. "/redirect/teacher" or "/redirect/student")
- Recommend: Icon with these specifications:
- Size: 24x24px
- Color: #919DA6
- File format: png and svg
- Optional: for mobile-app integration:
- Either you have your own iOS/Android app:
- Universal Link to open your iOS/Android app (e.g. "https://yourserver.com/app")
- To check if your app is already installed on the device:
- AppId for Android (e.g. "com.yourapp.school")
- AppId for iOS (e.g. "12532342")
- Or you have a mobile-view of your web-application and the redirect-pathes would also work on mobile devices:
- YES or NO
- Either you have your own iOS/Android app:
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/octet-stream; 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 and the signature in the headers.
Public Key - Integration-Stage:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxmHgTa7Qf4buurWraH9MqcEipr4YrMpIg1NVbV7sx2p1yhZ5HQ5hPfsuRRqk9ss7UYJS4dnTsjLCwJ1j91PmxZBnceSkgjHunZ53AxsQP7h/A8g3igbi+tRw6+9agyM8zRLeAaufQFvm6/81obezB54vjv1qPGXgX07cmgj2w2EMC39Q4S0eKVU8svjw3QTE0ZD7Gc92T+rMIhVrX5sAKviczs8VSA8CZnM7PDASZ/kjZF9umMfEzmxGm5BVCqMqpCTFh3CMljMmoH3lCro3r9Ve2Unl5Cc8wRJekSOIbpKJ54eVL6zwEExfPlTKQZslLKBhaNtquLJJkgV057ANDwIDAQAB
Public Key - Production:
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy4SObQ2nfru24gRbrx7L qWbvbYyeMgWu6rWk5PdnZ5hFDoabRIdQPeL8EEp/vHz2AUjArYefoNuSY+0stSAd LYpH5OKLxao2fTpwpZxj70DNEPlFPsjQznX9OyXiNEEGKrXdXuuCHYjUsEwgbZij bJXWba/DqPqs9KIzRZBTjAOMKlPIm0cTtQ63GgD41AQoXY9PWnH8mDjrCrwXIgNi Uw6imMUjsiR+kF9YP3+SizKDFoeiV7Xl6xdbi953OPVZ/KtSx2hn9RqH7jXv43TY XyRsRnDAH1mWt6ZAYJV+3JaCHGEwvN6yNQcnaBPWGXjw3s614iQgDR5EF0EpU4Jt OwIDAQAB
How to do in PHP:
Hint: If you are using PHP-FPM, check your htaccess-file and add "CGIPassAuth on". Otherwise there could be a problem, that the signature is not "visible" for your system.
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());