Skip to main content

OpenID Connect (OIDC) Login & Registration

Artemis supports decentralized user login and identity synchronization using OpenID Connect (OIDC). The OIDC feature acts as a secure, high-precedence authentication bridge. It allows identity providers to securely transmit verified student claims, including the matriculation number, name, and email directly into the Artemis ecosystem.

When a user authenticates via the OIDC provider for the first time, Artemis invokes Just-In-Time (JIT) provisioning. This automatically builds a native, stateless account record in the local database, extracting and mapping key attributes dynamically from the secure ID token.

  • The feature is fully controlled by the artemis.user-management.oidc.enabled: true module-feature flag.
  • If you run the system behind a reverse proxy, you must explicitly forward the following secure endpoints to the Artemis core instance: /oauth2/ and /login/oauth2/.

Architecture and Filtering Mechanics​

The OIDC ecosystem leverages Spring Security's OAuth2 Client libraries to inject an isolated, decoupled filter chain. This chain intercepts requests, ensuring OIDC callbacks are parsed and verified before hitting default platform filters.

Unlike standard stateless operations, the initialization flow briefly establishes a highly secured, short-lived HTTP session in RAM. This session acts as an anti-tampering buffer, storing state and cryptographic nonce parameters to shield the system against Cross-Site Request Forgery (CSRF) or token-replay mutations.

Configuration Specification​

The structure of the OIDC infrastructure configuration (standardized inside application-oidc.yml) dictates how Artemis bonds with the university identity pool:

artemis:
  user-management:
    oidc:
      enabled: true
      mappings:
        username: "preferred_username"
        matriculation-number: "matriculation_number"
        first-name: "given_name"
        last-name: "family_name"
        email: "email"

spring:
  security:
    oauth2:
      client:
        registration:
          oidc:
            provider: oidc
            client-id: "${ARTEMIS_OIDC_CLIENT_ID:placeholder-artemis-client-id}"
            client-secret: "${ARTEMIS_OIDC_CLIENT_SECRET:placeholder-artemis-client-secret}"
            scope:
              - "openid"
              - "profile"
              - "email"
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
            authorization-grant-type: "authorization_code"
        provider:
          oidc:
            issuer-uri: "${ARTEMIS_OIDC_ISSUER_URI:https://tumidp.lrz.de/idp/shibboleth}"
            authorization-uri: "${ARTEMIS_OIDC_AUTHORIZATION_URI:https://login.tum.de/idp/profile/oidc/authorize}"
            token-uri: "${ARTEMIS_OIDC_TOKEN_URI:https://login.tum.de/idp/profile/oidc/token}"
            user-info-uri: "${ARTEMIS_OIDC_USER_INFO_URI:https://login.tum.de/idp/profile/oidc/userinfo}"
            jwk-set-uri: "${ARTEMIS_OIDC_JWK_SET_URI:https://login.tum.de/idp/profile/oidc/keyset}"

info:
  oidc:
    # Customizable string used for the external login selection screen button (e.g. 'TUM Login')
    buttonLabel: "${ARTEMIS_OIDC_DISPLAY_NAME:TUM Login}"

Requested Scopes​

Artemis requests the scopes openid, profile and email unless you configure others. The property spring.security.oauth2.client.registration.oidc.scope accepts every form Spring Boot supports:

  • a YAML list, as in application-oidc.yml
  • one comma-separated value, for example SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_SCOPE='openid,profile,email'
  • one indexed environment variable per scope, for example SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_SCOPE_0='openid'

At startup Artemis logs the scopes it requests (OIDC login requests the scopes [...]). Check this line first when an identity provider does not release a claim you expect.

Matriculation Number with TUM Login​

TUM Login releases the matriculation number through the client-specific scope imMatrikelNr. TUM IT has to register this scope and the attribute of the same name for your client first. Request the scope and map the claim of the same name:

artemis:
  user-management:
    oidc:
      mappings:
        matriculation-number: "imMatrikelNr"

spring:
  security:
    oauth2:
      client:
        registration:
          oidc:
            scope: "openid,profile,email,imMatrikelNr"

Artemis stores the claim as the registration number of the account. It sets the number at the first login and updates it at later logins when it changed, unless another account already uses it. A blank or missing claim never deletes an existing number.

To see which claims an identity provider releases, look for this line in the server log after a login. It lists the claim names of the ID token and of the userinfo response, never their values, and states whether the configured matriculation claim is present:

OIDC login received the claims [...] in the ID token and [...] in the userinfo response. The configured matriculation claim 'imMatrikelNr' is present.

If the claim is missing, check the startup line for the requested scopes first, then ask the identity provider whether the scope is registered for your client.

Search documentation