Scopes
General Concepts
What is a scope?
Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.
You've probably already seen scopes in action (possibly without knowing that these are scopes) when you logged into to a third party with your Google or Facebook account.
What is a claim?
Claims are statements about an entity (typically, the user) and additional data. If the user gives consent to a scope the authorization server will, depending on the scope, add certain claims directly to the access token, idToken or make it available through the /userinfo endpoint.
Which scope should my application request?
Your application should only request the scopes it really needs to work correctly.
In general applications should request their scopes as late as possible. This way the user will be asked for the permissions he explicitly needs at that moment. For example if your application has the feature of sending notifications to the user by email but the user must enable this feature explicitly, your application does not need to access the End-User's email address before the End-User enables this feature. Therefore the email scope should only be requested, when the End-Users enables this feature.
Data Consistency
In general if a claim is specified as optional it may not be present (and therefore not mapped into the token). Your application needs to be able to handle these cases correctly.
Testing
TODO
Unscoped Claims
There are some claims that are added to every token, they can be found in the token documentation.
Overview
These are all the scopes that are currently available on the SIP Auth Service. Please note that some scopes are categorized as privileged.
| Scope | Description | Consent required | Privileged |
|---|---|---|---|
| address | access to the End-User's address | true | true |
| birthdate | access to the End-User's date of birth | true | true |
| access to the End-User's email | true | false | |
| employment-profile | access to the End-User's relevant information for employment such as AHV number | true | true |
| eth-affiliation | access to information about the users relationship to ETH Zurich (if any). | true | false |
| eth-legi-number | access to the ETH Legi-Number | true | true |
| eth-study-information | access to information about the studies of the End-User | true | true |
| eth-username | access to the nethz uernsame of the End-User (if he is a member of ETH Zurich) | true | false |
| iban | access to the End-User's IBAN number | true | true |
| gender | access to the End-User's gender | true | true |
| home-organization | access to the university affiliation of the user. | false | false |
| home-organization-uid | access to the End-User's homeOrganizationUUID (switch field). This should not be used if not required. | false | true |
| phone | access to the End-User's phone number | true | true |
| profile | access to general information about the user such as name and profile picture. | false | false |
| roles | false | false | |
| vseth-profile | access to information about the End-Users relationship with VSETH and the VSETH student association. | true | false |
| [web-origins] | false | false |
- offline_access
- web-origins
General Scopes
Address
The address scope can be requested to access the End-User's address.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| address | JSON | End-User's preferred postal address. The value of the address member is a JSON RFC4627 structure containing some or all of the members defined in Section 5.1.1 of the OIDC specification. | true | userinfo |
NOTE: The End-User's address may not be defined and the claim will be empty for certain user's. The client is responsible for handling this scenario.
Example
TODOBirthdate
The birthdate scope can be requested to access an End-User's birthdate.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| birthdate | string | End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format. | true | userinfo |
NOTE: The End-User's birthdate may not be defined and the claim will be empty for certain user's. The client is responsible for handling this scenario.
The email scope can be requested to access an End-User's email.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| string | End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being a unique identifier for a user, since a user may change his email address. | false | access token, IDToken, userinfo | |
| email_verified | boolean | True if the End-User's e-mail address has been verified; otherwise false. Since VSETH uses SWITCH AAI to authenticate users this value will always be set to true and is only present to work with 3rd party tools which use the value. | false | userinfo |
Employment-profile
COMING SOON
The employment-profile scope can be requested to access the End-User's employment information.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| nationality | string | TODO | true | |
| stay_permit | string | TODO | true | |
| civil_status | string | TODO | true | |
| ahv_number | string | TODO | true |
ETH-Affiliation
COMING SOON
The eth-affiliation scope can be requested to access information about the End-User's relationship with ETH Zurich.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| eth_department_short | string | The short name of the department according to the ETH Website. | true | userinfo |
| eth_department_name_de | string | The full name of the department in german according to the ETH Website | true | userinfo |
| eth_department_name_en | string | The full name of the department in english according to the ETH Website | true | userinfo |
ETH-Legi-Number
COMING SOON
The eth-legi-number scope can be requested to access a End-User's legi number.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| eth_legi_number | string | The End-User's legi number | false | userinfo |
NOTE: The End-User's eth_legi_number may not be defined and the claim will be empty for certain user's. The client is responsible for handling this scenario.
ETH-Username
The eth-username scope can be requested to access the End-User's nethz username, if he is a member of ETH Zurich.
| claim name | type | description | optional | token |
|---|---|---|---|---|
| eth_username | string | The eth username if defined. | true | access token, id token |
NOTE: The End-User's eth_study_program, eth_study_program_type, eth_semester may not be defined and the claim will be empty for certain user's. The client is responsible for handling this scenario.
ETH-Study-Information
COMING SOON
The eth-study-information scope can be requested to access the End-User's study information.
| claim name | type | description | optional | token |
|---|---|---|---|---|
| eth_study_program | string | The study program (Studiengang) the End-User is currently enrolled in. | true | userinfo |
| eth_study_program_type | string | The type of the study program, master, bachelor etc. | true | userinfo |
| eth_semester | int | The semester the End-User is currently enrolled in. | true | userinfo |
NOTE: The End-User's eth_study_program, eth_study_program_type, eth_semester may not be defined and the claim will be empty for certain user's. The client is responsible for handling this scenario.
IBAN
COMING SOON
The iban scope can be requested to access an End-User's iban number. The iban number is represented without spaces.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| iban | string | End-User's iban. | true | userinfo |
Gender
COMING SOON
The gender scope can be requested to access an End-User's gender.
VSETH uses the ISO/IEC 5218 to represent gender since this is the standard that is used by SWITCH and ETH Zurich. Check out the Switch Website for more information about the usage at SWITCH.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| gender | string | End-User's gender. The allowed values are: "not known", "female", "male", "not applicable" | true | userinfo |
| gender_code | int | End-User's gender as an integer as defined by ISO/IEC 5218. | true | userinfo |
home-organization
COMING SOON
The university-affiliation scope can be requested to access information about the End-User's affiliation to Swiss universities
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| home_organization | string | The home organization of the End-User as defined by SWITCH siwssEduPersonHomeOrganization. SWITCH also maintains a complete list of home organizations. The list defines the values that can be found in this claim. | false | userinfo |
| home_organization_type | string | The type of the home organization of the End-User as defined by SWITCH swissEduPersonHomeOrganizationType. | false | userinfo |
| home_organization_affiliation | string | The affiliation of the End-User to his/her home-organization as defined by the SWITCH eduPersonAffiliation. | false |
swiss-edu-person-unique-id
The university-affiliation scope can be requested to access the End-User's home organization unique identifier.
If this scope is present the following claims are mapped into the token:
do-not-use
This scope should not be used unless you know what you are doing. Please contact the ISG if you have any questions.
| claim name | type | description | optional | token |
|---|---|---|---|---|
| swiss_edu_person_unique_id | string | The home organization unique identifier of the End-User as defined by SWITCH. | false | access token, id token |
Phone
The phone scope can be requested to access an End-User's phone number.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| phone_number | string | End-User's phone number | true | userinfo |
| phone_number_verified | Currently not implemented |
NOTE: The End-User's phone may not be defined and the claim will be empty for certain user's. The client is responsible for handling this scenario.
Profile
The profile scope can be requested to access basic information about the End-User such as username and name.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| name | string | End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences. | false | access token, ID Token, userinfo |
| given_name | string | Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters. | false | access token, userinfo |
| family_name | string | Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters. | false | access token, userinfo |
| nickname | string | Casual name of the End-User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael. This value can be set by the End-User. If the value is not defined it defaults to the given_name | false | userinfo |
| preferred_username | string | Shorthand name by which the End-User wishes to be referred to at the RP, such as janedoe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace. The resource provider MUST NOT rely upon this value being unique. | false | access token, IDToken, userinfo |
| profile | string | URL of the End-User's profile page. | false | IDToken, userinfo |
| picture | string | URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User. At the moment this claim will contain a link to the Gravatar profile picture of the user for the email address. | true | IDToken, userinfo |
| website | string | URL of the End-User's Web page or blog. This Web page SHOULD contain information published by the End-User or an organization that the End-User is affiliated with. | true | userinfo |
| updated_at | number | Time the End-User's information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. | false | userinfo |
| Not supported yet | |||
|---|---|---|---|
| zoneinfo | string | String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles. | true |
| locale | string | End-User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties MAY choose to accept this locale syntax as well. | true |
VSETH-Profile
COMING SOON
The vseth-profile scope can be requested to access basic information about the vseth membership of the End-User.
If this scope is present the following claims are mapped into the token:
| claim name | type | description | optional | token |
|---|---|---|---|---|
| vseth_membership | boolean | Boolean indicating whether the End-User is a VSETH member. | false | access token, id token, userinfo |
| study_association | string | The orgID of the student association the End-User is a member of (if any). None if the End-User is not a member of a student association of VSETH. | false | access token, id token, userinfo |
| study_association_name_de | string | The name of the student association the user belongs to in german. | true | userinfo |
| study_association_name_en | string | The name of the student association the user belongs to in english. | true | userinfo |
API Specific scopes
COMING SOON