Skip to content

LS Login

LS Login (Life Science Login) is the identity provider of the ELIXIR On-Cloud: the Cloud Registry trusts it only. This page shows how to register a service, how LS Login releases group memberships to it (see Groups and facilities), and how to connect three services to LS Login: JupyterHub, HedgeDoc and MinIO.

For the registration of a service, and for everything else about LS Login, see the LS Login docs.

Register your service

Do this once for each service:

  1. Register the service in LS Login (see the LS Login docs).
  2. Open the SPREG tool.
  3. On the SAML/OIDC page, add the redirect URI of your service (see the sections below). LS Login compares the URI exactly: the host name alone is not enough.
  4. On the same page, copy the client ID and the client secret.
  5. Keep the client secret in a secret store, never in a repository.

Use one LS Login client for each service.

Test and production

LS Login keeps a new service in its test environment for at most 30 days. If its owner takes no action within another 14 days, LS Login deactivates the service (the LS Login team, December 2025). Move a service to production in time, as described in the LS Login docs.

The terms that apply to a registered service:

Both are linked, with the other policies, from the LS Login page.

Groups and facilities

Services of the ELIXIR On-Cloud that map LS Login groups to roles, such as the Cloud Registry, proTES and TESK (see Onboard a Node), see only the groups that LS Login releases to them. A user who is a member of a group but gets 403 Forbidden from such a service usually lacks the release, not the membership.

How LS Login releases groups

LS Login keeps its users, groups and services in Perun:

  • A virtual organisation (VO) holds groups, e.g., example_vo with the group example_group.
  • A facility represents a client (a registered service) in Perun.
  • A resource connects a facility with a VO. Groups of the VO are assigned to the resource.

LS Login puts a group into the user's entitlements only if the group is assigned to a resource on the facility of the client that requested the token. Membership alone is not enough: the same user gets a group from one client and not from another (see Perun's Entitlements).

Which client needs the groups

Assign the groups to the facility of the client that users log in to: the portal or front end that starts tasks or registers services. Services that only validate the tokens of that client (APIs such as proTES, TESK or the Cloud Registry) see the groups of that client; they don't need the groups on a facility of their own. A client that only gets tokens for a service itself (client credentials), with no users, needs no groups.

Assign only the groups that the services map to roles, e.g., example_vo:example_group:admins for admins, not every group of the VO.

With token exchange, the LS Login team says that the entitlements are computed for the client that calls the exchange. Which groups a service at the end of such a chain sees is still being tested.

Users outside the groups

To let anyone with an LS Login account log in to a client, not only the members of its groups, the LS Login team recommends a second resource on the client's facility, for the Lifescience VO, with the VO's members group assigned. Users outside the mapped groups can then log in, and services answer them with 403 Forbidden, so that a portal can tell them how to get access.

Assigning groups

  1. In Perun, open the facility of the client and create a resource for the VO that holds the groups.
  2. Assign the groups to the resource (see How to assign a group(s) to a resource). This takes the role TrustedFacilityAdmin within the VO (see Perun roles and their rights): being able to create the resource is not enough, and the button "Next" under "Assign groups" stays greyed out. If the VO's admins don't grant the role, send them links to the resource and to the groups, and ask them to assign the groups and confirm.
  3. Check that the groups are listed among the resource's assigned groups.
  4. Log in to the client with an account that is a member of a group, and read the released value (see Reading the entitlement values).

Reading the entitlement values

Group entitlements have this form (see Perun's Group entitlement):

urn:geant:lifescience-ri.eu:group:<vo>[:<group>[:<subgroup>]...]#aai.lifescience-ri.eu

For the group example_group of the VO example_vo:

urn:geant:lifescience-ri.eu:group:example_vo:example_group#aai.lifescience-ri.eu

Group names are URL-encoded, and the value changes when a group is renamed or moved. Services must match the exact value: don't guess it, read it from a token of the client.

LS Login releases the values in the user info only, not in the access token, in the claim eduperson_entitlement, and only if the client requested the scope eduperson_entitlement at login. The client's registration must allow that scope. To read the values, call the user info endpoint with an access token of the client. Read the token into a variable, so that it stays out of the shell history, and pass the header via standard input, so that it stays out of process listings:

read -rs TOKEN
printf 'Authorization: Bearer %s\n' "$TOKEN" | curl -fsS -H @- \
  --connect-timeout 10 --max-time 30 \
  https://login.aai.lifescience-ri.eu/oidc/userinfo

Handle tokens like passwords: never paste them into websites, tickets or chats.

How services read the groups

Services fetch the user info of each token and map its values to roles:

  • FOCA-based services, such as the Cloud Registry and proTES, add the claim from the user info with security.auth.userinfo_claims, read it with security.access_control.claim_groups and map values to roles with security.access_control.group_mapping (see Cloud Registry).
  • TESK reads one claim of the user info and accepts the listed values (see Onboard a Node). Whether TESK accepts LS Login tokens this way has not been verified yet (see the gaps listed there).

Checklist for a 403

If a user gets 403 Forbidden from a service that maps groups:

  1. Membership: is the user a member of the group in Perun?
  2. Release: is the group assigned to a resource on the facility of the client that the user logged in with (the token's aud), not of another client? For an exchanged token, check the facility of the client that called the exchange (see Which client needs the groups).
  3. Scope: did the client request eduperson_entitlement, and does the user info of the token list the group (see Reading the entitlement values)?
  4. Value: does the service map exactly the value in the user info, including the VO, the group path and #aai.lifescience-ri.eu?
  5. Caching: services may cache the user info for some minutes (the Cloud Registry for 5): a change applies after that, or with a new token.

JupyterHub

To deploy JupyterHub in the de.NBI Cloud, see this tutorial.

  1. Register the redirect URI https://{yourdomain}/hub/oauth_callback. Replace {yourdomain} with your host name.
  2. Add this to the config.yaml of the Helm chart (see the Zero to JupyterHub docs):
hub:
  config:
    Authenticator:
      allowed_users: # Only these LS Login users can log in
        - USER
      admin_users:
        - ADMIN # A user name that is an admin
    GenericOAuthenticator:
      client_id: # The client ID from SPREG
      client_secret: # The client secret from SPREG
      login_service: LS LOGIN
      oauth_callback_url: https://{yourdomain}/hub/oauth_callback
      authorize_url: https://login.aai.lifescience-ri.eu/oidc/authorize
      token_url: https://login.aai.lifescience-ri.eu/oidc/token
      userdata_url: https://login.aai.lifescience-ri.eu/oidc/userinfo
      username_claim: preferred_username # Newer versions
      username_key: preferred_username # Deprecated in newer versions
      scope:
        - openid
        - email
        - profile
    JupyterHub:
      authenticator_class: generic-oauth
cull:
  enabled: false

allow_all: true would let every LS Login user in. Keep the list of allowed users instead. Do not put the client secret into a values file that you commit: pass it at deploy time, for example from a secret store.

HedgeDoc

HedgeDoc reads its settings from environment variables. These steps assume that HedgeDoc is deployed already, for example with this Helm chart.

  1. Register the redirect URI of your HedgeDoc in SPREG (see the HedgeDoc docs).
  2. Add these environment variables to the deployment:
- name: CMD_OAUTH2_USER_PROFILE_URL
  value: https://login.aai.lifescience-ri.eu/oidc/userinfo
- name: CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR
  value: preferred_username
- name: CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR
  value: name
- name: CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR
  value: email
- name: CMD_OAUTH2_TOKEN_URL
  value: https://login.aai.lifescience-ri.eu/oidc/token
- name: CMD_OAUTH2_AUTHORIZATION_URL
  value: https://login.aai.lifescience-ri.eu/oidc/authorize
- name: CMD_OAUTH2_CLIENT_ID
  value: _REPLACE BY CLIENT ID_
- name: CMD_OAUTH2_CLIENT_SECRET
  value: _REPLACE BY CLIENT SECRET_
- name: CMD_OAUTH2_PROVIDERNAME
  value: ELIXIR On-Cloud
- name: CMD_OAUTH2_SCOPE
  value: openid email profile

MinIO

You can turn on LS Login in the MinIO console (OIDC settings) or with environment variables (see the MinIO docs):

export MINIO_IDENTITY_OPENID_CONFIG_URL="https://login.aai.lifescience-ri.eu/oidc/.well-known/openid-configuration"
export MINIO_IDENTITY_OPENID_CLIENT_ID="<ID of the LS Login service>"
export MINIO_IDENTITY_OPENID_CLIENT_SECRET="<Secret of the LS Login service>"
export MINIO_IDENTITY_OPENID_DISPLAY_NAME="<Label of the login button, e.g., LS Login>"
export MINIO_IDENTITY_OPENID_SCOPES="<Scopes to request, e.g., openid,email,profile>"
export MINIO_IDENTITY_OPENID_ROLE_POLICY="<Policy for LS Login users, e.g., readonly>"
export MINIO_IDENTITY_OPENID_CLAIM_USERINFO="on"

MinIO has two ways to authorize users with OIDC (see the MinIO docs). Use the RolePolicy flow: MinIO assigns each LS Login user to one or more policies. A policy can limit access to a bucket, for example to the members of an LS Login group (see policy-based access control).

This policy gives the listed users, identified by their preferred_username claim, read access to the bucket sensitive:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::sensitive",
                "arn:aws:s3:::sensitive/*"
            ],
            "Condition": {
                "StringEquals": {
                    "jwt:preferred_username": [
                        "ELIXIR_USERNAME"
                    ]
                }
            }
        }
    ]
}