Authentication
Single sign-on (SSO)
The more identities a user has to manage, the greater the risk of a credential-related security incident. More identities mean more passwords to remember and change. Password policies can vary between applications and, as complexity requirements increase, it becomes increasingly difficult for users to remember them.
VSETH uses SSO wherever possible as an integral component of the Student Innovation Platform (SIP).
Securing Applications: Authentication and User Authorization
This page describes how you can authenticate users on the SIP and get user authorization to access APIs. For Authenticating 3rd party applications that can not use OpenID Connect please contact the ISG.
If you have read the model section of the auth documentation were we tried to separate the three concepts:
- Authentication of a user
- Getting authorization from a user
- Checking authorization of a user.
were clearly distinct from each other.
This page will show hands-on how you can do the first two things with the SIP auth service. Please note that this does not include of actually checking whether a user has the authorization to access a certain resource. Please refer to the Authorization guide.
You can also test out the authentication by going to https://echo.tvseth.ethz.ch
Primer on the used technologies
Warning
If you have never worked with OpenID Connect or similar modern web authentication standards it might be very confusing. Please take the time to watch this short primer.
Authorization Grants
There are three authorization grants that can be used to authenticate the user and obtain user authorization on the SIP:
- Authorization Code
- Implicit Grant
- Client Credentials Flow
These grant types have different fields of application:
| Grants | Access User Resources | Requires Client Secret | Access Token Refresh | Additional Information |
|---|---|---|---|---|
| Authorization Code | Yes | Yes | Yes | The authorization code grant requires that the client can safely store a client secret, which is not exposed to the outside world. That's why this grant is only suitable for clients with a backend and not frontend-only clients. |
| Implicit Grant | Yes | No | No | The implicit grant should only be used if the code grant can not be used, because it is less safe than the code grant. |
| Client Credentials | Yes | No | No | The client credentials grant is only used for service-accounts in the VSETH setup, because since we're using the SWITCH AAI service for authentication, VSETH does not process passwords of End-Users. (A service-account is not a user account but a client. We create an individual client for every service accessed by another service.) |
TODO: Tokens?
Authorization code
The authorization code grant type is used to obtain access tokens and / or id tokens and / or refresh tokens and should be used for all applications which have a backend that can keep a secret. For further information please checkout the OAuth 2.0 (RF-6749) Standard.
- You do: Prompt you user to a webpage where they can choose to grant you access to their data.
- You get: Access token, id token and optional also a refresh token.
TODO
1. Have your application request authorization from the End-User
- Rediret the user to the /auth endpoint of the SIP Auth service.
Implicit grant
The implicit grant grant type is used to obtain access tokens and / or id tokens (it does not support refresh tokens) and should be used for public clients that can no use the authorization code grant type because they can not keep a secret private. This grant type is mainly used for Java Script clients running in the End-Users Browser.
- You do: Redirect the user to the SIP Login service
- You get: Access token and / or ID Token
1. Have your application request authorization from the End-User
- Redirect the user to the
/authendpoint of the SIP Auth service.
GET https://auth.vseth.ethz.ch/auth/realms/VSETH/protocol/openid-connect/auth
The request needs to include the following parameters in the URL:
| Query Parameter | Value |
|---|---|
| client_id | Required The client ID of your application, this is provided by the `` SIP variable. |
| response_type | Required Can either be set to token, id_token or both of them, depending on what you want to do. |
| redirect_uri | Required The URI to redirect after the user grants / denies permission. This URI needs to be specified in the sip.yml file, because the auth service will validate the URI to which it redirects (for security reasons) |
| state | Optional The state parameter can be used by the application to carry some state. This will be added to the redirect as an URI parameter. |
| scope | Optional A space-separate list of scopes. Check out the available scopes in the scope documentation |
Example
You redirect the user:
https://auth.vseth.ethz.ch/auth/realms/VSETH/protocol/openid-connect/auth?This perform the following actions:
- The user is redirected to the SWITCH AAI Login, which will first ask the End-User to specify his home organization. After the End-User has selected her home organization she is then redirected to the login screen of her home organization, where she will be asked to login.
- After the (successfull) she is then asked to authorize the given client within the scopes.
- The user is redirected back to the specified URI.
Please note: Steps (1) and (2) may occur without user interaction if the user already has already logged in with SWITCH AAI (Step 1 will not require user interaction) or has already authorized the client for the given scope (Step 2 will not require user interaction).
If the user grants access, the final URI will contain an URI fragment with the following data encoded as a query string.
| Query Parameter | Description |
|---|---|
| access_token | The JWT OAuth2 Access token which can be used to query APIs. |
| id_token | The JWT id token which can be used to get information about the user. |
| token_type | |
| expires_in | Time when the token will expire. |
| state | The optional state parameter which was sent from the client. This parameter will not be modified. |
[Optional] 2. Use the id token to get information about the user
If you requested an ID Token you can now use the ID Token to authenticate the user. The ID Token is a JWT which can be decoded.
For example decoding the token yields:
[Optional] 3. Use the access token to query an API
TODO
More Information
For more information about the implicit grant grant type check out the respective sections of the OAuth 2.0 specification and the OpenID Connect specification.
Client Credentials
TODO
Service Accounts
Service Accounts are accounts used by services to authenticate with each other. They are individually created in Keycloak and are actually clients, not users. As a norm, we create a service account for each service used by an application. (For example, if my app needs e-mail and pay, we create two service accounts: sa-mail-<app-name> and sa-payment-<app-name> to authenticate with the Mail API and the Payment API, respectively.
As an application developer, you can generate tokens for such service accounts via direct access grant. For Golang, CLI Auth implements everything you need. The handling of these tokens is exactly the same as for "normal" user tokens.
Creating Service Accounts
For production, ask the ISG. For testing, you must extend your local Keycloak service with a new client (which will be the service account). We recommend the following naming scheme:
sa-<target-api-name>-<app-name>
Example smtp service account:
<targetAPI> - <AppName>
sa-<mail-vseth>-<wordpress-zuun>
You must change the client's access type to confidential. After this, you will find the login credentials for this account under the tab "Credentials". You can map this client to audiences (via the "Mappers" tab) and, if needed, assign it different roles ("Service Account Roles" tab).