Authorization
Attention: For all Authorization-Flows, you have to use the WebUntis-URL (WU-URL)!
For Userinterface
This Authorization-Flow (aka OpenId Connect Code grant Flow) serves to authorize an user between WebUntis and your 3rd-Party-Application including the neccessery Sessions/Cookies.
Call authorize Endpoint
GET: {{WEBUNTIS_URL}}/WebUntis/api/sso/{{SCHOOL-name}}/authorize/
?response_type=code
&scope=roster-core.readonly openid
&client_id={OIDC Client ID}
&redirect_uri={third_party_url}
&nonce=1234
Example:
1GET https://nightly.webuntis.com/WebUntis/api/sso/nightlyhry/authorize/?response_type=code&scope=roster-core.readonly%20openid&client_id=Berry2b&school=nightlyhry&redirect_uri=berry2b.example.domain.at/redirect?nonce=1234Important:
- You need an active WU-session to get an id token!
- The redirect_uri must match the configured domain + redirect-path in the platform-application-manager! Otherwise you get an “invalid_ressource” error.
- If you add the scope “untis-profile” you will get more information about the user in the JWT-token, but we cannot guarantee the backwards compatibility of this information. Changes might lead to developing-effort in your application. Better to use only the “sub” and call the OneRoster-User-Endpoint to get the information.
Get Access Token
POST: {{WEBUNTIS_URL}}/WebUntis/api/sso/{{SCHOOL}}/token/
?grant_type=authorization_code
&code={authorization_code from the first Endpoint}
&client_id={OIDC Client ID}
&client_secret={OIDC Secret}
Example:
1POST https://nightly.webuntis.com/WebUntis/api/sso/nightlyhry/token/?grant_type=authorization_code&code=HmToMB_iITpHLucs8RvrL8pEi6iizoKKK7_W8lJSi0k&redirect_uri=berry2b.example.domain.at/redirect&client_id=Berry2b&client_secret=Rd5kweLWyww9TYPjjrrvCq3MnCnzezuUsInfo: The response JWT-token includes the userinformation ("sub")!
Important: The header must include 'Content-Type: application/x-www-form-urlencoded'
For API-Integration
This Credentials-Flow (aka Client credentials grant OAuth2.0) serves to establish a Server2Server-Communication, so you can call our REST-APIs like OneRoster.
In our case, the OIDC Client ID is the username and we don’t use the OIDC secret as a password, we use a self-generated password. The password is generated when activating the platform-application.
Get Access Token
POST: {{WEBUNTIS_URL}}/WebUntis/api/sso/{{SCHOOL-name}}/token
?grant_type=client_credentials
The header must include Basic Auth (based on username=OIDC Client ID and Password generated by the Platform-Application-Manager).
The body must include grant_type=client_credentials. (Postman Body: x-www-form-urlencoded)
Example:
1{{WU_URL}}WebUntis/api/sso/{{SCHOOL}}/token?grant_type=client_credentialsInfo:
- Get an access_token of type “Bearer” within the body response. With this token you can call the OneRoster-Endpoints.
- The token is valid for 3 minutes.
GET /.well-known/openid-configuration
Returns the OpenID Connect configuration values from our Well-Known Configuration Endpoint, per the specification (OIDC-Spec).