Two-step verification EAP guide

[#1]

The solution is still in alpha version. Please, DO NOT use it in a production instances, but rather in an isolated test environment.

This guide is also available as pdf in the Google Drive's main catalog that will be shared with EAP participants.

Requesting access

The artefacts are stored on a Google Drive. Please send an email to dc-2sv-alpha@atlassian.com:

• titled "2SV EAP drive access request",
• listing up to three corporate email addresses that should have access to the artefacts.

We will grant access within one working day.

Enabling two-step verification

1. Once the product and plugin are installed (see the Installation paragraph below), the new login page should be visible out-of-the-box. 

2. After successful login, to enable two-step verification, the user can navigate to User icon (top right) → User profile → ‘Two-step verification’ tab. 

3. To enable two-step verification, click ‘Unlock settings’ and provide password, confirming the action with ‘Verify identity’.

4. The settings should be unlocked and it should be possible to click Set up

5. After clicking ‘Set up’, the enrollment page should be displayed with QR code and Verification code input. To enable two-step verification, the QR code should be scanned with a mobile app which supports TOTP verification (such as Duo or Google Authenticator). Once scanned and confirmed in the mobile app, the TOTP code displayed in the mobile app should be provided in the Verification code input. 

6. Then, a confirmation page should be displayed with the emergency recovery key provided. 

7. After clicking ‘Saved, let’s finish' the two-step verification functionality should be available during the next login

Available functionality

• 2SV login via TOTP - UI login flow enriched with two-step verification based on TOTP

• 2SV login via recovery key - UI login flow enriched with two-step verification based on the recovery key. The key is created during 2SV enrollment.

• 2SV enrollment - enabling 2SV for the user via UI

• 2SV unenrollment - disabling 2SV for the user via UI

• 2SV change authentication app - switch to another 2SV authentication app via UI

• 2SV enforcement - enforcing system admins to enable 2SV on login via UI

  • the functionality is disabled by default. To enable it, specify the JVM flag before instance start-up: -Datlassian.authentication.2sv.enforcement.enabled=true
    
    To set properties follow:

    • For Jira https://confluence.atlassian.com/adminjiraserver/setting-properties-and-options-on-startup-938847831.html

    • For Confluence: https://confluence.atlassian.com/doc/configuring-system-properties-168002854.html

• Legacy mode - switch login page behavior to old one (without 2SV capability) via runtime parameter

  • The legacy mode is disabled by default. To enable it, specify the JVM flag before instance start-up: -Datlassian.authentication.legacy.mode=true
    
    To set properties follow:

    • For Jira https://confluence.atlassian.com/adminjiraserver/setting-properties-and-options-on-startup-938847831.html

    • For Confluence: https://confluence.atlassian.com/doc/configuring-system-properties-168002854.html

• Emergency 2SV unenrollment - REST API which allows system admin to unenroll other user as documented below:

URL	rest/tsv/latest/totp/unenroll/user/{userName}
Method	delete
Summary	Unenroll the user with specified userName from 2SV, accessible only via REST API for admins to provide unenrollment option if the user cannot do it by themselves.
Request	Path: {userName} - user name (String) Body: { "totpCode": "<TOTP code>" }
Responses	204 - User unenrolled successfully 400 - there’s no enrollment for specified user {message: 'No enrollment found for this user.'} 404 - user not found 401 - invalid TOTP code

Installation

Confluence

1. Download the EAP product artifact directly from the official Atlassian website: Confluence Early Access Program (EAP) Downloads | Atlassian

2. Install the application in your test environment following the guide: Confluence Installation Guide | Confluence Data Center 9.0 | Atlassian Documentation

3. The product should start successfully and the new login page should be visible for further testing

Jira / JSM

Installation for Jira/JSM is more complicated since the public EAP is not yet released (as it’s for Confluence).

1. Download the product artifact from the official Atlassian website

   1. Jira 10.0 Jira Data Center Download Archives | Atlassian

   2. Jira Service Management 10.0 Jira Service Management Download | Atlassian

2. Install the application in your test environment following the guide: Installing Jira applications | Administering Jira applications Data Center 10.0 | Atlassian Documentation

3. Reenable ‘plugin upload via marketplace’ and start the product: How to re-enable plugin upload in Jira Data Center | Jira | Atlassian Documentation

4. Download the latest authentication plugin JAR: Plugin

5. Install the authentication plugin JAR via UPM following ‘Install an app from a file’ steps Installing Marketplace apps | Atlassian Support | Atlassian Documentation

6. Ensure the plugin ‘Authentication for Atlassian Data Center’ has successfully started. The new feature should be available in the product.

[Pawel Cieszko]

Hello everyone,

The guide and plugin version have been updated.

Please note that for Confluence testing it's sufficient to use the recent public Confluence 9.1 EAP version.

Best regards,

Pawel Cieszko