oauth2

Abstract from the oauth2 standard.

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

https://tools.ietf.org/html/rfc6749The oauth2 specification is quite good and therefore this documentation page about oauth2 takes a quite minimalistic approach, only explaining the things that are not clear from the specification (from the author's perspective) while also giving some more examples in a VSETH context..

General points (that a lot of people get wrong):

oauth2 only deals with AUTHORIZATION but doesn't care about AUTHENTICATION (this is what openid-connect is used for).

Concepts

Registering Clients

Terms

Term	Explanation	Example in VSETH context
Resource Owner	The person / entity that grants access to a protected resource. Resource Ownership can also be shared by multiple persons.	Each user of an vseth application is the resource owner for his own private data e.g. his email address or profile information. If you create an event in the eventmanager application you become the resource owner of this event. But if you give other users also access to edit your events, they too become resources owners of this protected resource.
End-User	A resource owner that is also a person.	-
Resource Server	The server application hosting the protected resources. Should be able to handle requests to the resources by checking access tokens.	The people-api of VSETH acts as a resource server. If the user has the necessary access token, the client may request data from the people-api.
Client	An application making protected resource requests on behalf of the resource owner. (independent on which platform the client is running)	The VSETH golden owl may query a backend service to get all the lectures a given user has signed uf for in the last two semesters.
Authorization server	The server issuing access tokens to the client after successfully authenticating the resource	Keycloak is the VSETH Authorization Server.
Authorization Grant	An authorization grant is a piece of cryptographic material proving that the resource has given the authorization to a client to access a certain protected resource by getting an access token for it. There are four different authorization grants defined by the oauth2 specification. Authorization Code Implicit Resource Owner Password Credentials Client Credentials The inner workings are defined in the specification. For VSETH the resource owner password credentials is not used.	TODO: Login flow golden OWL
Authorization Code	Is one of the authorization grants supported by the oauth2 specification.
Implicit	Is one of the authorization grants supported by the oauth2 specification.
Resource Owner Password Credentials	Is one of the authorization grants supported by the oauth2 specification.
Client Credentials	Is one of the authorization grants supported by the oauth2 specification.
Access Token	Access tokens are credentials used to access protected resources. An access token is a string representing an authorization issued to the client. The string is usually opaque to the client. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server.	VSETH uses JWT for access tokens.
Refresh Token	Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).
Client Type: confidential
Client Type: public

OpendID Connect

Specification: https://openid.net/specs/openid-connect-core-1_0.html#Introduction

Different Tokens

ID token: Identity card for each users, contains information about the user which is signed as a JWT token and can therefore be used by a client.
Access token: Token that caries information about the user
Userinfo: Userinfo endpoint may be called with an access token to get information as a user as a JSON object or jwt.

Claims

Access Token ist ein super set vom ID Token

Standard OpenId Connect

Member	Type	Description	VSETH Usage	Keycloak Scope	Optional
sub	string	Subject - Identifier for the End-User at the Issuer.	-	-	FALSE
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.		profile	FALSE
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.		profile	FALSE
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.		profile	FALSE
middle_name	string	Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.	No (eth ldap doesn't use middlenames)	profile	-
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.	Yes (for the moment set to given_name)	profile	FALSE
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 RP MUST NOT rely upon this value being unique, as discussed in Section 5.7.	nethz name ext-$email, equal to unique_username	profile	FALSE
profile	string	URL of the End-User's profile page. The contents of this Web page SHOULD be about the End-User.	Yes	profile	TRUE
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.	Yes	profile	TRUE
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.	Yes	profile	TRUE
email	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 unique, as discussed in Section 5.7.	Yes	email	FALSE
email_verified	boolean	True if the End-User's e-mail address has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating.	Mapping auf True (da AAI)	email	FALSE
gender	string	End-User's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable.	Yes	gender	TRUE
birthdate	string	End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed. Note that depending on the underlying platform's date related function, providing just year can result in varying month and day, so the implementers need to take this factor into account to correctly process the dates.	Yes	birthdate	TRUE
zoneinfo	string	String from zoneinfo [zoneinfo] time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles.	Yes Browser Mapping?	profile	?
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.	Yes Browser Mapping?	profile	?
phone_number	string	End-User's preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678.	Yes	phone	TRUE
phone_number_verified	boolean	True if the End-User's phone number has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this phone number was controlled by the End-User at the time the verification was performed. The means by which a phone number is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. When true, the phone_number Claim MUST be in E.164 format and any extensions MUST be represented in RFC 3966 format.	Yes	phone	TRUE
address	JSON object	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.	Yes	address	TRUE
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.	Yes	profile	TRUE

VSETH Claim

Member	Type	Description	VSETH Usage	Keycloak Scope	Optional
unique_username	string		Yes	profile	FALSE

vseth_membership	boolean		Yes	vseth-profile	FALSE
study_association	string: OrgID \| "None"		Yes	vseth-profile	FALSE
study_association_name_de	string			vseth-profile	TRUE (only for members)
study_association_name_en	string			vseth-profile	TRUE (only for members)
home_organization	string	example: "ethz.ch" / "uzh.ch" as provided by switch.		university-affiliation	FALSE
affiliation	string			university-affiliation	FALSE
department_short	string			eth-affiliation	TRUE
department_name	string			eth-affiliation	TRUE
STUDIENGANG_TYP; BSC / MSC etc.	string			eth-affiliation	TRUE
FACHRICHTUNG; Fachrichtung	string			eth-study-information	TRUE
STUDIENGANG; Studiengang	string			eth-study-information	TRUE
STUDIENPLANSEMESTER; Studiengang				eth-study-information	TRUE
legi_number	string		Yes	eth-legi-number	TRUE

Scope	Consent
profile	No
email	Yes
gender	Yes
birthdate	Yes
phone	Yes
address	Yes
vseth-profile	No
university-affiliation	No
eth-affiliation	Yes
eth-study-information	Yes
eth-legi-number	Yes

Claims

https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

Access Token

Scopes
Roles

User Attribute

ETH Account Typ (Gast / kein Gast)