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:
- Register the service in LS Login (see the LS Login docs).
- Open the SPREG tool.
- 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.
- On the same page, copy the client ID and the client secret.
- 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:
- Terms of Use for Service Providers;
- the LS AAI service level declaration, which says what services that depend on LS Login can expect of it.
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_vowith the groupexample_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¶
- In Perun, open the facility of the client and create a resource for the VO that holds the groups.
- 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.
- Check that the groups are listed among the resource's assigned groups.
- 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):
For the group example_group of the VO example_vo:
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 withsecurity.access_control.claim_groupsand map values to roles withsecurity.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:
- Membership: is the user a member of the group in Perun?
- 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). - Scope: did the client request
eduperson_entitlement, and does the user info of the token list the group (see Reading the entitlement values)? - Value: does the service map exactly the value in the user info,
including the VO, the group path and
#aai.lifescience-ri.eu? - 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.
- Register the redirect URI
https://{yourdomain}/hub/oauth_callback. Replace{yourdomain}with your host name. - Add this to the
config.yamlof 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.
- Register the redirect URI of your HedgeDoc in SPREG (see the HedgeDoc docs).
- 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: