Initiated Login

Users will normally jump into your application from their Eduplaces dashboard by clicking on the activated Tile. We will open your application in a new tab. For a great user experience, you should automatically log the user in and not show them a login screen. Since we can not include any ID or access tokens when opening your application for security reasons, you will have to start a regular authentication flow. This should all be done in the background without the user noticing anything.

When registering your application, we will ask you for a Login URL. This is the URL we will redirect users to after they clicked on your Tile in their dashboard. You should use this URL to automatically start an authentication flow.

Handling the Login URL

We will pass two query parameters to your Login URL:

  • iss - Our Issuer Identifier https://auth.eduplaces.io.
  • login_hint (optional) - A token our authentication server will use to make sure the correct user is logged in to your application.

While the last parameter is optional by specification, we will always include it for now. Just make sure not to rely on it as this might change in the future. If login_hint is present, you have to include it in the authentication request you send to our authorization server.

If you are testing your integration in the Sandbox environment, the iss parameter will be https://auth.sandbox.eduplaces.dev instead.
GET https://your.awesome-education.app/sso/login
    ?iss=https://auth.eduplaces.io
    &login_hint=30e58376-ed53-4c5b-91c1-9fd5517e7f55

In this example https://your.awesome-education.app/sso/login is the Login URL. You can use any URL you want as long as you handle the query parameters correctly.

Note: This is part of the OpenID Connect protocol. You should be able to reuse this endpoint for other OpenID Connect providers as well. That's why the iss parameter is included.

Starting an Authentication Flow

When your application receives a request to the Login URL, it should start an authentication flow. Both authentication flows available for Single Sign-On are suitable for this. You should only start an authentication flow with Eduplaces, if the passed iss parameter is https://auth.eduplaces.io.

You can either start an Authorization Code Flow with PKCE (recommended) or an Authorization Code Flow. In addition to the usual parameters, you have to include the login_hint parameter in the authentication request you send to our authorization server. Just pass the value you received in the login_hint parameter of the Login URL.

There is already a user logged in

Receiving a request to the Login URL should always start a new authentication flow. If a user is already logged in to your application, you should log them out and start a new authentication flow. This is necessary to make sure that the correct user is logged in to your application. If you don't do this, an Eduplaces user could open your application via the dashboard, but be logged in as a different user from a previous session.

Mobile platforms

If you are building a mobile application, you can also use the Login URL to start your application and then start an authentication flow. Both iOS and Android support to open your mobile application instead of your website in the browser. On iOS, you can use Universal Links and on Android you can use Android App Links.

For example, you can register your mobile applications to handle all https://your.awesome-education.app/ URLs. When we redirect the user to https://your.awesome-education.app/sso/login on a mobile device, your application will be opened instead of your website in the browser. If your application is not installed or the user is on a desktop device, the browser will just open your website instead.

As both platforms support deep linking, you can also access the iss and login_hint parameters in your application and start an authentication flow right away. For mobile applications, only the Authorization Code Flow with PKCE is supported.

What for?

You might ask yourself, why we can't just send the user to your application with an ID and access token right away. Wouldn't it be much easier for you to just receive the tokens and log the user in automatically? It would. But it would also be highly insecure. If we would include the tokens in the request to your application, any other website could do the same. This would make your website vulnerable to Cross-Site Request Forgery (CSRF) and token replay attacks.

Both OAuth 2.0 and OpenID Connect have mechanisms to mitigate these attacks. They both rely on the fact that you include a random value in the request to our authorization server and check if it is present in our response. If the value is missing or does not match, you know that the request was not initiated by your application and you can reject it.

Table of Contents