Scopes

OAuth 2.0 is a standard protocol that allows users to grant limited access to their resources on one site (for instance, Eduplaces), to another application, without having to expose their credentials. It's akin to giving someone a key that can only unlock certain rooms in a house, rather than handing over the master key (the users password). We provide a short introduction to OAuth 2.0 and explain the different flows available at Eduplaces in our Authorization section.

Scopes play a pivotal role in this setup. In the context of OAuth 2.0, a scope can be thought of as a specific permission or a set of permissions. When an external ed-tech application, like yours, wants to access specific information or functionalities on Eduplaces, it doesn't request carte blanche access. Instead, it specifies which "rooms" it needs access to, by requesting the appropriate scopes.

For example, if an application only needs to view student profiles but not modify them, it would request a scope like "read:student_profiles" and not something broader like "edit:student_profiles." Note: These are fictional scopes, but you get the idea.

This modular approach offers multiple benefits:

1. Security: By limiting access to only what's necessary, risks associated with potential data breaches or mishandling of data are minimized.
2. User Trust: When users see that your application is only requesting the permissions it truly needs, they are more likely to trust and grant the necessary access.
3. Flexibility: Scopes allow partners like you to tailor integrations to specific needs, ensuring streamlined operations without extraneous access.

As you proceed with integrating your application with Eduplaces, understanding and appropriately requesting OAuth 2.0 scopes will be essential to ensure a seamless, secure, and efficient connection between our platforms. Data protection and privacy are of the utmost importance to us, and we expect the same from our partners. We therefore will only grant access to scopes that are necessary for your application to function.

Type of Scopes

There are two types of scopes available at Eduplaces: Resource scopes and OpenID Connect scopes. Resource scopes are used to access specific endpoints of our API, while OpenID Connect scopes are used to access information about the user. The later will not grant you access to any additional API endpoints but will provide you with additional information about the user during the authentication process.

OpenID Connect Scopes

OpenID Connect scopes are used to access information about the user during the authentication process. They do not provide you with access to any additional API endpoints. During the authentication process, you'll receive an ID token containing information about the user. The information contained in the ID token depends on the scopes you requested during the authentication process.

List of available OpenID Connect scopes:

• openid: This scope is required for all OpenID Connect requests.
• school: This scope provides access to the user's internal school ID.
• profile: This scope provides access to the user's name.
• pseudonym: This scope provides access to the user's randomly generated pseudonym if the account is not yet personalized.
• role: This scope provides access to the user's role within the school.
• groups: This scope provides access to the user's groups.

• school_location: This scope provides access to the user's school location.
• school_address This scope provides access to the user's school address.
• school_name: This scope provides access to the user's school name.
• school_official_id: This scope provides access to the user's school official ID.

openid

This scope is required for all OpenID Connect requests. It is used to identify the request as an OpenID Connect request and to provide you with an ID token containing information about the user. The default ID token will contain the following information:

{
  "iss": "https://auth.eduplaces.io", // Issuer
  "aud": [ // Audience
    "dc61f99d-adfe-458a-86bf-3a316f2a789c" // Always the client ID of your application
  ],
  "sub": "f80763f1-96da-4071-b29d-1f15d83ca8b6", // ID of the user whom the token refers to
  "jti": "30e58376-ed53-4c5b-91c1-9fd5517e7f55", // Unique identifier for this token
  "sid": "7ddc71e6-e932-43e5-9d86-2ada68a490af", // Session ID
  "at_hash": "cw8qL0ENYRYrslktjHXEtw", // Access token hash
  "auth_time": 1692706900, // Time the user authenticated
  "rat": 1692706896, // Requested at timestamp
  "iat": 1692706914, // Issued at timestamp
  "exp": 1692710514, // Expiration timestamp
}

You can request additional information by requesting additional scopes.

school

{
  // ...
  "school": "e7b26853-9513-427f-a782-6f1729ae1801"
  // ...
}

profile

{
  // ...
  "name": "Johanna Becker",
  "given_name": "Wilma Johanna Sophie",
  "call_name": "Johanna",
  "family_name": "Becker"
  // ...
}

pseudonym

{
  // ...
  "pseudonym": "Mathe Ninja",
  // ...
}

role

{
  // ...
  "role": "TEACHER",
  // ...
}

groups

{
  // ...
  "groups": [
    {
      "id": "3cd81e40-615a-4882-b328-2fbb3417d6bd",
      "name": "Klasse 5a"
    }
  ],
  // ...
}

schooling_level

{
  // ...
  "school_type": "PRIMARY_SCHOOL",
  // ...
}

school_location

{
  // ...
  "school_location": {
    "country": "DE",
    "state": "NI"
  },
  // ...
}

school_address

{
  // ...
  "school_address": {
    "address": "Hauptstraße 1",
    "address_addition": "c/o Schulleitung",
    "city": "Hasenwinkel",
    "zip_code": "12345"
  },
  // ...
}

school_name

{
  // ...
  "school_name": "IGS Hasenwinkel",
  // ...
}

school_official_id

{
  // ...
  "school_official_id": "DE-NI-18K6",
  // ...
}

Resource Scopes

Resource scopes are currently exclusively used internally by Eduplaces and are not available to external applications.