Authorization
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.
Attention: Because of these cookies, its necessary to use the WebUntis-URL (WU-URL) to call the authorize-Endpoint.
Call authorize Endpoint
GET: {{WEBUNTIS_URL}}/WebUntis/api/sso/v2/{{tenantId}}/authorize/
?response_type=code
&scope=roster-core.readonly openid
&client_id={OIDC Client ID}
&redirect_uri={third_party_url}
&nonce=1234
Example:
1GET https://tom.integration.webuntis.dev/WebUntis/api/sso/v2/1234/authorize/?response_type=code&scope=roster-core.readonly%20openid&client_id=BestApp&redirect_uri=bestapp.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/v2/{{tenantId}}/token/
?grant_type=authorization_code
&code={authorization_code from the first Endpoint}
&client_id={OIDC Client ID}
&client_secret={OIDC Secret}
Example:
1POST https://tom.integration.webuntis.dev/WebUntis/api/sso/v2/1234/token/?grant_type=authorization_code&code=HmToMB_iITpHLucs8RvrL8pEi6iizoKKK7_W8lJSi0k&redirect_uri=berry2b.example.domain.at/redirect&client_id=BestApp&client_secret=Rd5kweLWyww9TYPjjrrvCq3MnCnzezuUs
Info: 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: {{EAP_URL or WU-URL}}/WebUntis/api/sso/v2/{{tenantId}}/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:
1https://api.integration.webuntis.dev/WebUntis/api/sso/v2/1600/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).
You can get the right endpoints calling the well-known-endpoint via the EAP-URL:
Example:
https://api.webuntis.com/WebUntis/api/sso/v2/{tenantid}/.well-known/openid-configuration