Difference between revisions of "BwForCluster User Access/2FA Tokens"

From bwHPC Wiki
Jump to: navigation, search
(Registering a new Software or Hardware Token)
(27 intermediate revisions by the same user not shown)
Line 3: Line 3:
   
 
'''Currently this description is only valid for bwForCluster JUSTUS 2.'''
 
'''Currently this description is only valid for bwForCluster JUSTUS 2.'''
  +
  +
'''When there is an old useless software token (i.e. not initialized, smartphone lost, etc) or an old dysfunctional backup TAN list (i.e. no printout), delete those BEFORE setting up a new TOTP token and a backup TAN lists.'''
  +
  +
'''After cleaning up your old tokens, FIRST set up a software/hardware TOTP token. THEN create and print a backup TAN list in addition.'''
   
 
----
 
----
Line 14: Line 18:
 
A six-digit auto-generated time-dependent '''One-Time Passwords''' (TOTP) is used. These TOTPs are generated either by a special hardware device ('''hardware token''') or by an application running on a smartphone or computer ('''software token''').
 
A six-digit auto-generated time-dependent '''One-Time Passwords''' (TOTP) is used. These TOTPs are generated either by a special hardware device ('''hardware token''') or by an application running on a smartphone or computer ('''software token''').
   
The token has to be synchronized with a central server before it can be used for authentication and then generates an endless stream of six-digit values which can only be used once and are only valid during a very short interval of time. This makes it much harder for potential attackers to access the HPC system, even if they know the regular service password.
+
The token has to be synchronized with a central server (a shared secret is exchanged) before it can be used for authentication and then generates an endless stream of six-digit values (TOTP values) which can only be used once and are only valid during a very short interval of time. This makes it much harder for potential attackers to access the HPC system, even if they know the regular service password.
  +
  +
Typically a new TOTP value is generated every 30 seconds. When the current TOTP value has once been used successfully for a login, it is depleted and one has to wait up to 30 seconds for the next TOTP value.
   
 
== Hardware tokens ==
 
== Hardware tokens ==
Line 62: Line 68:
 
= Token Management =
 
= Token Management =
   
'''bwForCluster tokens''' are generally managed via the '''My Tokens''' menu entry on the central [https://bwidm.scc.kit.edu/ bwIDM registration server]. Here you can register, activate, deactivate and delete tokens.
+
'''bwForCluster tokens''' are generally managed via the '''Index (old: User) -> My Tokens''' menu entry on the central [https://login.bwidm.de/ bwIDM registration server]. Here you can register, activate, deactivate and delete tokens.
   
 
Usually a TOTP token that has been connected to your account is valid for all clusters on the registration server. Thus you can use the same TOTP token for bwUniCluster 2.0 and JUSTUS 2.
 
Usually a TOTP token that has been connected to your account is valid for all clusters on the registration server. Thus you can use the same TOTP token for bwUniCluster 2.0 and JUSTUS 2.
   
 
'''KIT users''' can also re-use their existing hardware and software tokens for the HPC systems.
 
'''KIT users''' can also re-use their existing hardware and software tokens for the HPC systems.
  +
  +
'''In addition to your regular hardware/software token we recommend to register at least one backup TAN list''', i.e. for emergencies when access to your regular hardware/software token has been lost. You should print and store the backup TAN list at a safe location.
  +
  +
See chapter 2.1 for details about how to register a new software/hardware token and chapter 2.2 for details about how to create and use a backup TAN list.
   
   
 
== Registering a new Software or Hardware Token ==
 
== Registering a new Software or Hardware Token ==
   
1. First you need to login to the [https://bwidm.scc.kit.edu/ bwIDM registration server] (if you are not logged in already).
+
1. First you need to login to the [https://login.bwidm.de/ bwIDM registration server] (if you are not logged in already).
   
2. After login please select entry '''My Tokens''' in the '''User''' menu.
+
2. After login please select entry '''My Tokens''' in the '''Index (old: User)''' menu.
   
 
3. If you have not setup any tokens yet you can directly proceed with step 4 below (since token management is accessible directly for users without tokens). Otherwise (a token is already connected to your account) you need to log into the token management by entering a TOTP and clicking on '''Check'''.
 
3. If you have not setup any tokens yet you can directly proceed with step 4 below (since token management is accessible directly for users without tokens). Otherwise (a token is already connected to your account) you need to log into the token management by entering a TOTP and clicking on '''Check'''.
   
4. Registering a new token starts with a click on '''New smartphone token'''. If you happen to own a USB hardware token device made by the manufacturer '''[https://www.yubico.com Yubikey]''', you can click on '''New Yubikey Token''' instead.
+
4. Registering a new software token starts with a click on '''New smartphone token'''.
   
[[File:BwUniCluster 2.0 2fa register new empty.png|center|]]
+
[[File:JUSTUS-2-2FA-create-a-new-token-here.png|center|]]
   
 
5. A new windows opens. Click on '''Start''' to generate a new '''QR code'''. This may take a while.
 
5. A new windows opens. Click on '''Start''' to generate a new '''QR code'''. This may take a while.
Line 89: Line 99:
 
6. Start the software token app on your separate device and scan the QR code. The exact process is a little bit different in every app, but is usually started by pressing on a button with a plus (+) sign or an icon of a QR code.
 
6. Start the software token app on your separate device and scan the QR code. The exact process is a little bit different in every app, but is usually started by pressing on a button with a plus (+) sign or an icon of a QR code.
   
7. Once the QR code has been loaded into your software token app there should be a new entry called '''bwIDM'''. Generate an One-Time-Password by pressing on this entry or selecting the appropriate button/menu item. You will receive a six-digit code. Enter this code into the field labeled "Current code:" in your bwIDM browser window to prove that the connection has worked and then click on '''Check'''.
+
7. Once the QR code has been loaded into your software token app there should be a new entry called '''bwIDM'''.
   
  +
8. Generate an One-Time-Password by pressing on this entry or selecting the appropriate button/menu item. You will receive a six-digit code. Enter this code into the field labeled "Current code:" in your bwIDM browser window to prove that the connection has worked and then click on '''Check'''.
8. If everything worked as expected, you will be returned to the '''My Tokens''' screen and there will be a new entry for your Software Token:
 
  +
  +
9. If everything worked as expected, you will be returned to the '''My Tokens''' screen and there will be a new entry for your Software Token:
   
 
[[File:BwUniCluster 2.0 2fa register new success.png|center|]]
 
[[File:BwUniCluster 2.0 2fa register new success.png|center|]]
   
  +
10. Repeat the process to register additional tokens.
9. Repeat the process to register additional tokens. '''Please register at least a Backup TAN list in addition to the hardware/software token you plan to use regularly.''' If you only register a single token and happen to lose access to it, e.g. because you lose your device, uninstall the software token application or data gets deleted/corrupted, you will neither be able to log into the cluster system nor register a new token. In such a case please follow instructions of the next section.
 
  +
  +
11. '''Please register at least a Backup TAN list in addition to the hardware/software token you plan to use regularly (see chapter 2.2 for that).''' If you only register a single token and happen to lose access to it, e.g. because you lose your device, uninstall the software token application or data gets deleted/corrupted, you will neither be able to log into the cluster system nor register a new token (see chapter 3 on how to request a reset of all tokens).
  +
  +
12. If you are in the process to register for a bwForCluster, then you can proceed with the next step [https://wiki.bwhpc.de/e/BwForCluster_User_Access#Personal_registration_at_a_bwForCluster_-_account_creation on the registration server].
  +
  +
== Generate a new Backup TAN List ==
  +
  +
1. First you need to login to the [https://login.bwidm.de/ bwIDM registration server] (if you are not logged in already).
  +
  +
2. After login please select entry '''My Tokens''' in the '''Index (old: User)''' menu.
  +
  +
3. If you have not setup any tokens yet you can directly proceed with step 4 below (since token management is accessible directly for users without tokens). Otherwise (a token is already connected to your account) you need to log into the token management by entering a TOTP and clicking on '''Check'''.
  +
  +
4. To generate a backup TAN list, click on '''Create new TAN list'''.
  +
  +
[[File:JUSTUS-2-2FA-create-a-new-token-here.png|center|]]
  +
  +
5. A new window opens. Click on button '''Start''' to create the backup TAN list.
  +
  +
6. If everything worked as expected, the new '''Backup TAN list''' is displayed:
  +
  +
[[File:JUSTUS-2-2FA-backup-TAN-list.png|center|]]
  +
  +
7. Click on button '''Show TANs''' and then on button '''Print'''. Print the TAN list and store the printout at a safe location.
  +
  +
8. The 8 digit TANs of the backup TAN list can be used in precisely the same way as the TOTP values created with your hardware or software token. Remember: Once used, the TAN is not valid any more.
   
 
= Recovery when access to all tokens has been lost =
 
= Recovery when access to all tokens has been lost =
   
To gain access again after you have lost access to all your tokens including the backup TAN list, please contact the [[BwForCluster_JUSTUS_Contact_and_Support|JUSTUS 2 support]] via bwSupport Portal '''(NOT email !!!)''' and ask for reset of all your TOTP tokens. This process will take its time.
+
To gain access again after you have lost access to all your tokens including the backup TAN list, please contact the [[BwForCluster_JUSTUS_Contact_and_Support|JUSTUS 2 support]] via bwSupport Portal '''(NOT email)''' and ask for reset of all your TOTP tokens. This process will take its time.
   
 
= Deactivating a Token =
 
= Deactivating a Token =

Revision as of 12:28, 16 February 2021


Currently this description is only valid for bwForCluster JUSTUS 2.

When there is an old useless software token (i.e. not initialized, smartphone lost, etc) or an old dysfunctional backup TAN list (i.e. no printout), delete those BEFORE setting up a new TOTP token and a backup TAN lists.

After cleaning up your old tokens, FIRST set up a software/hardware TOTP token. THEN create and print a backup TAN list in addition.



To improve security a 2-factor authentication mechanism (2FA) is being enforced for logins to the bwForCluster. In addition to the service password a second value, the second factor, has to be entered on every login.


1 How 2FA works

A six-digit auto-generated time-dependent One-Time Passwords (TOTP) is used. These TOTPs are generated either by a special hardware device (hardware token) or by an application running on a smartphone or computer (software token).

The token has to be synchronized with a central server (a shared secret is exchanged) before it can be used for authentication and then generates an endless stream of six-digit values (TOTP values) which can only be used once and are only valid during a very short interval of time. This makes it much harder for potential attackers to access the HPC system, even if they know the regular service password.

Typically a new TOTP value is generated every 30 seconds. When the current TOTP value has once been used successfully for a login, it is depleted and one has to wait up to 30 seconds for the next TOTP value.

1.1 Hardware tokens

Generally hardware tokens are available for users from the Karlsruhe Institute of Technology (KIT). Every KIT member automatically gets a hardware token when joining the KIT.


Hardware Token used at KIT


1.2 Software tokens

Software tokens (typically an app on your smartphone) are available for all bwHPC users.

It is very important that the device that generates the One-Time Passwords and the device which is used to log into the bwForCluster are not the same. Otherwise an attacker who gains access to your system can steal both the service password and the secret key of the software token application, which allows them to generate One-Time Passwords and log into the HPC system without your knowledge.

The most common solution is to use a mobile device (e.g. your smartphone or tablet) as a software token by installing one of the following apps:

  • GNOME Authenticator for Linux

Open source apps for Android are available via f-droid store: andOTP Authenticator, Aegis Authenticator and Yubico Authenticator.

These are only suggestions. You can use any application compatible with the TOTP standard.

An example of the FreeOTP app on Android, displaying generated One-Time Passwords for various services

2 Token Management

bwForCluster tokens are generally managed via the Index (old: User) -> My Tokens menu entry on the central bwIDM registration server. Here you can register, activate, deactivate and delete tokens.

Usually a TOTP token that has been connected to your account is valid for all clusters on the registration server. Thus you can use the same TOTP token for bwUniCluster 2.0 and JUSTUS 2.

KIT users can also re-use their existing hardware and software tokens for the HPC systems.

In addition to your regular hardware/software token we recommend to register at least one backup TAN list, i.e. for emergencies when access to your regular hardware/software token has been lost. You should print and store the backup TAN list at a safe location.

See chapter 2.1 for details about how to register a new software/hardware token and chapter 2.2 for details about how to create and use a backup TAN list.


2.1 Registering a new Software or Hardware Token

1. First you need to login to the bwIDM registration server (if you are not logged in already).

2. After login please select entry My Tokens in the Index (old: User) menu.

3. If you have not setup any tokens yet you can directly proceed with step 4 below (since token management is accessible directly for users without tokens). Otherwise (a token is already connected to your account) you need to log into the token management by entering a TOTP and clicking on Check.

4. Registering a new software token starts with a click on New smartphone token.

JUSTUS-2-2FA-create-a-new-token-here.png

5. A new windows opens. Click on Start to generate a new QR code. This may take a while.

NOTE: The QR code contains a key which has to remain secret. Only use the QR code to link your software token app with bwIDM in the next step. Do not save the QR code, print it out or share it with someone else. You can always generate more codes later.

BwUniCluster 2.0 2fa register new qr.png

6. Start the software token app on your separate device and scan the QR code. The exact process is a little bit different in every app, but is usually started by pressing on a button with a plus (+) sign or an icon of a QR code.

7. Once the QR code has been loaded into your software token app there should be a new entry called bwIDM.

8. Generate an One-Time-Password by pressing on this entry or selecting the appropriate button/menu item. You will receive a six-digit code. Enter this code into the field labeled "Current code:" in your bwIDM browser window to prove that the connection has worked and then click on Check.

9. If everything worked as expected, you will be returned to the My Tokens screen and there will be a new entry for your Software Token:

BwUniCluster 2.0 2fa register new success.png

10. Repeat the process to register additional tokens.

11. Please register at least a Backup TAN list in addition to the hardware/software token you plan to use regularly (see chapter 2.2 for that). If you only register a single token and happen to lose access to it, e.g. because you lose your device, uninstall the software token application or data gets deleted/corrupted, you will neither be able to log into the cluster system nor register a new token (see chapter 3 on how to request a reset of all tokens).

12. If you are in the process to register for a bwForCluster, then you can proceed with the next step on the registration server.

2.2 Generate a new Backup TAN List

1. First you need to login to the bwIDM registration server (if you are not logged in already).

2. After login please select entry My Tokens in the Index (old: User) menu.

3. If you have not setup any tokens yet you can directly proceed with step 4 below (since token management is accessible directly for users without tokens). Otherwise (a token is already connected to your account) you need to log into the token management by entering a TOTP and clicking on Check.

4. To generate a backup TAN list, click on Create new TAN list.

JUSTUS-2-2FA-create-a-new-token-here.png

5. A new window opens. Click on button Start to create the backup TAN list.

6. If everything worked as expected, the new Backup TAN list is displayed:

JUSTUS-2-2FA-backup-TAN-list.png

7. Click on button Show TANs and then on button Print. Print the TAN list and store the printout at a safe location.

8. The 8 digit TANs of the backup TAN list can be used in precisely the same way as the TOTP values created with your hardware or software token. Remember: Once used, the TAN is not valid any more.

3 Recovery when access to all tokens has been lost

To gain access again after you have lost access to all your tokens including the backup TAN list, please contact the JUSTUS 2 support via bwSupport Portal (NOT email) and ask for reset of all your TOTP tokens. This process will take its time.

4 Deactivating a Token

Click on the Disable button next to the Token entry on the My Tokens screen.

5 Deleting a Token

After a Token has been disabled a new button labeled Delete will appear. Click on it to delete the Token.