# Authentication

> University of Münster CIT provides DFN-AAI/edugain federated authentication via a central SATOSA OpenID Connect proxy.

---

Site [llms.txt](/llms.txt)

---

## OpenID Connect

OpenID Connect (OIDC) is a widely used extension to the Oauth2 protocol.
It provides an easy method for authenticating clients and serving user information to services.

## Request OIDC Client

Any institution or work group at the University of Münster can request an OpenID Connect (OIDC) client.

To request a new client, please fill out the [request form](/forms/oidc-client-application). The form contains all information required for the client registration.

### Submission

After completing the form, send the request by email to `cloud@uni-muenster.de` using your university email account.

You may either:

- submit the form directly, or
- download the generated `.yaml` file and attach it manually to your email.

Please digitally sign the email using your personal university certificate.

If you do not yet have a personal certificate, instructions for requesting and using one can be found [here](https://www.uni-muenster.de/CA/de/howto-mail.shtml).

### Note for Outlook Users

Microsoft Outlook may use the outdated `SHA1` hashing algorithm for digital signatures by default. Since `SHA1` is considered insecure by modern cryptographic libraries, such signatures will be rejected by our ticket system.

If you use Outlook, please ensure that a modern hashing algorithm such as `SHA256` is configured for your digital signature.

Step-by-step instructions can be found in [these instructions](https://www.uni-muenster.de/CA/en/howto-setup-exchange.shtml). Search for the keywords `Hashalgorithmus` or `hash algorithm`.

### Setup

Setting up the service typically requires a `client_id`, `client_secret`, `redirect_uri` and the OIDC discovery endpoint, which is found at: [https://auth.k8s.wwu.de/.well-known/openid-configuration](https://auth.k8s.wwu.de/.well-known/openid-configuration).
If you which to use Oauth2 instead of OIDC, you may use the `token_endpoint` and `jwks_uri` from the discovery information.
The service also needs to be configured to request scopes, which are determined by the attributes you require.
Please see the next section on the connection between attributes and scopes.
Remember, that your service can only access attributes, that have been granted on application.

### Attributes

On application, you have to request access to attributes, such as the email address, given name or family name of the users.
Due to data privacy regulations, only a small subset of really required attributes can be assigned to the service.
Some of the attributes, like POSIX or group information is only available for accounts from University of Münster.
Please be reminded, that due to privacy policies, many attributes have to be explicitly requested at foreign identity providers to be submitted to our service provider.

```
Scopes -> Attributes Mapping:

openid:
  - sub
  - epuid
  - pairwise-id
profile:
  - name
  - given_name
  - family_name
email:
  - email
orcid:
  - orcid
posix:
  - uid
  - gid
  - gids
account:
  - eppn
  - username
  - groups
  - systems
  - domain
  - affiliation
  - entitlement
  - assurance
  - userstatus
```

### Transparent Authentication in Kubernetes

We provide transparent authentication for webservices in our Kubernetes cluster.
Please contact [kube@uni-muenster.de](mailto:kube@uni-muenster.de) with the desired attributes.
We forward the `id_token` as signed JWT to your application using the `Authorization: Bearer` header.
The information in the JWT can be used in Istio `RequestAuthentication` and `AuthorizationPolicy` resources to restrict access to your website based on the information in the token.

This requires your pod to be part of the [service mesh](/docs/kubernetes/network/servicemesh/#adding-a-pod-into-the-service-mesh), i.e. it must run with an Istio sidecar, since the sidecar is what validates the JWT and enforces the authorization policy.

The `RequestAuthentication` defines the trusted issuer and validates the JWT, while the `AuthorizationPolicy` restricts access based on claims contained in the token, such as `groups` or `affiliation`. The following example only allows requests through the Ingressgateway that carry a valid token issued by `https://auth.k8s.wwu.de` for the audience `karma`, with the group `u0system@uni-muenster.de` and the affiliation `employee@uni-muenster.de`. It also allows Prometheus to scrape the `/metrics` endpoint without authentication:

```yaml
apiVersion: security.istio.io/v1
kind: RequestAuthentication
metadata:
  name: karma
  namespace: karma
spec:
  jwtRules:
    - issuer: https://auth.k8s.wwu.de
      jwksUri: https://auth.k8s.wwu.de/oidc/jwks
  selector:
    matchLabels:
      app.kubernetes.io/instance: karma
      app.kubernetes.io/name: karma
---
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: karma
  namespace: karma
spec:
  action: ALLOW
  rules:
    - from:
        - source:
            principals:
              - cluster.local/ns/istio-ingressgateway/sa/istio-ingressgateway-service-account
      to:
        - operation:
            methods: ["GET", "POST", "DELETE"]
            ports: ["8080"]
      when:
        - key: request.auth.claims[iss]
          values: ["https://auth.k8s.wwu.de"]
        - key: request.auth.claims[aud]
          values: ["karma"]
        - key: request.auth.claims[groups]
          values: ["u0system@uni-muenster.de"]
        - key: request.auth.claims[affiliation]
          values: ["employee@uni-muenster.de"]
    - from:
        - source:
            principals:
              - cluster.local/ns/prometheus/sa/prometheus-prometheus
        - source:
            principals:
              - cluster.local/ns/prometheus-tenants/sa/prometheus-tenants-tenants-prometheus
      to:
        - operation:
            methods: ["GET"]
            paths: ["/metrics"]
            ports: ["8080"]
  selector:
    matchLabels:
      app.kubernetes.io/instance: karma
      app.kubernetes.io/name: karma
```