External authentication

Authentication API

The authentication API for the GEWIS website uses JWT tokens and it's usage is described below.

Token

Tokens are JWT tokens. They are signed with the app secret. They always have the type HS512.

Tokens have the following contents:

• lidnr of the GEWIS Member
• Expiration time in UTC (tokens are valid for 5 minutes)
• Creation time in UTC
• Nonce

Based on additional needs by the external application, the following claims can be added:

• email => e-mail address
• family_name => given surname or last name
• given_name => given name or first name
• is_18_plus => whether or not the member is 18+
• membership_type => type of membership
• middle_name => middle name

However, the usage of these claims has to be motivated to and subsequently approved by the GEWIS privacy responsible.

Apps

An app has the following properties:

• Name (just for identification)
• appId (public)
• secret (shared between app and the GEWIS Website)
• callback (URL to be called after authentication)
• url (URL to the homepage of the application)

The callback and url are required to be hosted on a website that supports SSL/TLS (URL starts with https).

Basic flow

• User requests login from the app
• App redirects to https://gewis.nl/token/{appId}
• User logs in on the GEWIS website if needed
• On first authentication the user should authorise the app / if the user has not used the app they will be reminded
• If the user authorises the app, the GEWIS website redirects to {callback}?token={token}
• The app verifies the token

Alternative:

• If the user does not authorise the app, the GEWIS website redirects to {url} (i.e., the homepage of the app)

See also the sequence diagram below:

Verifying a token

To verify the token, the following needs to be verified:

• The HMAC of the token (most JWT libraries should do this automatically, but verify this)
• Expiration time of the token (it shouldn't be expired)