{"__v":23,"_id":"56fb86c70023171700b95fee","category":{"__v":2,"_id":"560111b06811d00d00ceb34e","pages":["56011249f01fb90d00d4bf70","56013a3e6811d00d00ceb381"],"project":"55edea207145f717001ac12c","version":"55edea207145f717001ac12f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-22T08:30:40.352Z","from_sync":false,"order":9999,"slug":"plugins","title":"Plugins"},"project":"55edea207145f717001ac12c","user":"55ede9ed1452cd0d009e5e6b","version":{"__v":11,"_id":"55edea207145f717001ac12f","project":"55edea207145f717001ac12c","createdAt":"2015-09-07T19:48:48.670Z","releaseDate":"2015-09-07T19:48:48.670Z","categories":["55edea217145f717001ac130","55ffa8038c0c9d0d00dcac72","55ffbaa48c0c9d0d00dcac88","55ffbd3e8c0c9d0d00dcac8b","55ffbee40e2b090d00863393","55ffc4306932a00d00ba7a85","55ffc66bfeaf310d007dd6c8","55ffc9c2feaf310d007dd6d1","55ffceca0e2b090d008633b2","560111b06811d00d00ceb34e","560262e74f15002100ee4445"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-30T07:56:55.851Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":999,"body":"#Rublon Two Factor Authentication for JIRA\n\n----------\n\n\n##About the plugin\n\nRublon Two Factor Authentication for JIRA is a plugin that provides the second factor of authentication often described as \"something that the user possesses\". In this case it is a mobile phone, which you use to scan a QR code. After scanning Rublon checks if user used the correct device. If the device matches to the one stored in database, user gets authenticated. The first factor (something that the user knows) is handled by Seraph Authenticator (default authenticator for JIRA). The second factor is provided by a custom filter, called just after the original JIRA security filter. All communication between client and server in JIRA goes through it.  If user is remembered with a cookie, the first factor is being skipped, user is getting authenticated with the cookie and redirected to Rublon where the second factor authentication process is being held. In case of potential problems you can disable the filter usage by editing a few lines of configuration file, therefore plugin will not prevent administrator from logging in and uninstalling it.\n\n\n## First steps ##\n\nTo start using the Rublon Two Factor Authentication plugin for JIRA you should:\n\n- install the Rublon mobile app on your smartphone, create a new account and confirm your email address\n- visit the Rublon Developer Area at developers.rublon.com and log in by clicking the \"Developer Dashboard\" button, and scanning the QR code that will appear using the Rublon mobile app\n- go to the \"Add website\" form (Dashboard -> Add website) and fill in the required fields\n- as Technology, from the expandable list, choose \"Jira\"\n- copy the provided system token and secret key, which will be used to identify the integrated system and verify the authenticity and integrity of the messages exchanged with Rublon API (you will need it later while configuring your JIRA).\n\n\n## Installation\n\nAt the beginning you should download Jira installation package using following link:\n[block:embed]\n{\n  \"html\": false,\n  \"url\": \"https://admin.rublon.com/public/resources/jira/rublon-2fa-plugin-jira-1.0.2.zip\",\n  \"title\": null,\n  \"favicon\": null\n}\n[/block]\nthen please install Rublon Two Factor Authentication plugin from Atlassian Marketplace available at:\n[block:embed]\n{\n  \"html\": false,\n  \"url\": \"https://marketplace.atlassian.com/plugins/com.rublon.jira.plugins.twofactorauthentication/server/overview\",\n  \"title\": \"Rublon Two-Factor Authentication\",\n  \"favicon\": \"https://marketplace-cdn.atlassian.com/s/528/images/favicon.ico\",\n  \"image\": \"https://marketplace-cdn.atlassian.com/files/images/baa24376-f2e5-4070-8aef-040dc8158e6c.jpeg\",\n  \"iframe\": false\n}\n[/block]\n### Automatic installation\n\nTo install Rublon Two Factor filter module first you need to locate your JIRA installation top directory.\n\n##### Windows\nOpen INSTALL.cmd file to perform automatic installation. After running the file you will be asked for JIRA location, enter the location you have found earlier and press ENTER. After checking if the path is correct, bash file will search for missing files and copy it to /lib folder. \n\n##### Unix\nRun INSTALL.sh file to perform automatic installation. After running the file you will be asked for JIRA location, enter the location you have found earlier and press ENTER. After checking if the path is correct, bash file will search for missing files and copy it to /lib folder. \n\n###Manual installation\n\nTo install Rublon Two Factor plugin for JIRA first you need to locate your JIRA installation top directory. For a further reference let's call it $JIRA_INSTALLATION.\n\n1. Install the Rublon Two-Factor Filter JAR:  \n\tCopy rublon-2fa-filter.jar and paste it in your lib directory.\n \n\n\t\tcp jar/rublon-2fa-filter.jar $JIRA_INSTALLATION/atlassian-jira/WEB-INF/lib\n\n2. Install the Java SDK Rublon JAR:  \n\tCopy java-rublon-sdk.jar and paste it in your lib directory.\n\n\t\tcp jar/java-rublon-sdk.jar $JIRA_INSTALLATION/atlassian-jira/WEB-INF/lib\n\n3. Install the JSON JAR:  \n\tCopy org.json.jar and paste it in your lib directory.\n\n\t\tcp jar/org.json.jar $JIRA_INSTALLATION/atlassian-jira/WEB-INF/lib\n\n4. **(Recommended)** Compare JIRA /lib directory with /optional_jars directory in installation package. It is recommended to copy every file you are missing. Make sure not to duplicate any of files (even if versions differ). The most common file that may be missing is **httpclient**.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"If you didn't follow the fourth step and have problems with JIRA, copy the rest of files in /optional_jars directory. Make sure **not to duplicate** any of files (even if versions differ).\",\n  \"title\": \"\"\n}\n[/block]\n## Automatic Configuration\n\nYou can configure you Rublon Two-Factor Authentication plugin using configuration page. In order to do it you need to visit Manage Add-ons section, find Rublon plugin on the list and press the \"Configure\" button. On the page you will be asked to enter Secret Key and System Token, values you generated earlier in Rublon Developer Area. After entering proper values you have to select \"Rublon Two-Factor Authentication\" and press the \"Save\" button. You have to restart your JIRA server for the changes to take effect.\n\n## Manual Configuration\n\nIf you chose not to configure JIRA using configuration page or encountered any errors during the process, please follow instructions below.\n\nLocate web.xml file for your JIRA. It should be located in:\n\n\t$JIRA_INSTALLATION/atlassian-jira/WEB-INF/web.xml\n\n\nOpen it and find the following fragment:\n\n\t<filter>\n        <filter-name>security</filter-name>\n        <filter-class>com.atlassian.jira.security.JiraSecurityFilter</filter-class>\n    </filter>\n\nPaste the following fragment below:  \n[use correct values for <param-value> of secret.key and system.token (generated in first steps on developers.rublon.com)]\n\n\t<filter>\n    \t<filter-name>rublon</filter-name>\n    \t<filter-class>com.rublon.jira.plugins.servlet.filter.RublonAuthenticationFilter</filter-class>\n    \t<init-param>\n      \t\t<param-name>system.token</param-name>\n      \t\t<param-value>Enter proper system token value here</param-value>\n    \t</init-param>\n    \t<init-param>\n     \t\t<param-name>secret.key</param-name>\n      \t\t<param-value>Enter proper secret key value here</param-value>\n    \t</init-param>\n\t</filter>\n\nFind the following fragment:\n\n\t<filter-mapping>\n\t\t<filter-name>security</filter-name>\n\t\t<url-pattern>/*</url-pattern>\n\t\t<dispatcher>REQUEST</dispatcher>\n\t\t<dispatcher>FORWARD</dispatcher> <!-- we want security to be applied after urlrewrites, for example -->\n\t</filter-mapping>\n\nPaste the following fragment below: \n\n\t<filter-mapping>\n\t\t<filter-name>rublon</filter-name>\n\t\t<url-pattern>/*</url-pattern>\n\t\t<dispatcher>FORWARD</dispatcher>\n\t\t<dispatcher>REQUEST</dispatcher>\n\t</filter-mapping>\n\nYou have to restart your JIRA server for the changes to take effect.\n\n## Disabling the plugin\n\nYou can deactivate the plugin in plugin configuration page by selecting \"Default Authentication\" instead of \"Rublon Two-Factor Authentication\". You can also do it manually by taking the following steps:  \nFind filter nodes added earlier:\n\n\t<filter>\n    \t<filter-name>rublon</filter-name>\n    \t<filter-class>com.rublon.jira.plugins.servlet.filter.RublonAuthenticationFilter</filter-class>\n    \t<init-param>\n      \t\t<param-name>system.token</param-name>\n      \t\t<param-value>Enter proper system token value here</param-value>\n    \t</init-param>\n    \t<init-param>\n     \t\t<param-name>secret.key</param-name>\n      \t\t<param-value>Enter proper secret key value here</param-value>\n    \t</init-param>\n\t</filter>\n\nand\n\n\t<filter-mapping>\n\t\t<filter-name>rublon</filter-name>\n\t\t<url-pattern>/*</url-pattern>\n\t\t<dispatcher>FORWARD</dispatcher>\n\t\t<dispatcher>REQUEST</dispatcher>\n\t</filter-mapping>\n\nDelete both entries or comment them out using following brackets:\n\n\t<!-- entry -->\n\nYou have to restart your JIRA server for the changes to take effect.\n\n### Optional\n\nYou can also delete plugin lib files, but it is not recommended to delete files other than rublon-2fa-filter.jar and java-rublon-sdk.jar unless you are sure it is not used by any other plugin. Before deleting any file it is recommended to make a backup copy of potentially unused files.\n\n## Known Issues\n\nWhile trying to login using Dashboard login gadget in JIRA 6 or older you may encounter an error:\n\n> Sorry, your username and password are incorrect - please try again.\n\nIn this case you can try to refresh a website or click Log In button in the top right corner or enter address of login.jsp directly in the address bar.\n\n> $HOST/jira/login.jsp\n\nIt is also possible to force a redirection to login page upon trying to access Dashboard without being logged in.\n\n1. While being logged in as an administrator press \"g\" button twice to open a search bar\n2. Find an Announcement Banner\n3. Enter the following JS script\n\n\t\t<script>\n\t\tif(jQuery('#header-details-user-fullname').text().indexOf(\" \") ==-1 && window.location.href.indexOf(\"/secure/Dashboard.jspa\") != -1)\n\t\t{ window.location = contextPath+\"/login.jsp\" }\n\t\t</script>\n4. Set visibility level to public and accept changes by clicking on Set Banner button\n\nThis short script will redirect to login.jsp page whenever unauthenticated user tries to access Dashboard. If logged in user tries to access Dashboard he won't be redirected.\n\nYou can also disable the login gadget on the Dashboard.\n\n1. Locate you JIRA home directory (it contains dbconfig.xml).\n2. Edit jira-config.properties file, if file doesn't exist you should create one.\n3. Add the following line to the config file:\n\t\t\n\t\tjira.disable.login.gadget=true\n4. Save the edited file.\n5. Restart your JIRA server.","excerpt":"","slug":"jira","type":"basic","title":"Jira"}
#Rublon Two Factor Authentication for JIRA ---------- ##About the plugin Rublon Two Factor Authentication for JIRA is a plugin that provides the second factor of authentication often described as "something that the user possesses". In this case it is a mobile phone, which you use to scan a QR code. After scanning Rublon checks if user used the correct device. If the device matches to the one stored in database, user gets authenticated. The first factor (something that the user knows) is handled by Seraph Authenticator (default authenticator for JIRA). The second factor is provided by a custom filter, called just after the original JIRA security filter. All communication between client and server in JIRA goes through it. If user is remembered with a cookie, the first factor is being skipped, user is getting authenticated with the cookie and redirected to Rublon where the second factor authentication process is being held. In case of potential problems you can disable the filter usage by editing a few lines of configuration file, therefore plugin will not prevent administrator from logging in and uninstalling it. ## First steps ## To start using the Rublon Two Factor Authentication plugin for JIRA you should: - install the Rublon mobile app on your smartphone, create a new account and confirm your email address - visit the Rublon Developer Area at developers.rublon.com and log in by clicking the "Developer Dashboard" button, and scanning the QR code that will appear using the Rublon mobile app - go to the "Add website" form (Dashboard -> Add website) and fill in the required fields - as Technology, from the expandable list, choose "Jira" - copy the provided system token and secret key, which will be used to identify the integrated system and verify the authenticity and integrity of the messages exchanged with Rublon API (you will need it later while configuring your JIRA). ## Installation At the beginning you should download Jira installation package using following link: [block:embed] { "html": false, "url": "https://admin.rublon.com/public/resources/jira/rublon-2fa-plugin-jira-1.0.2.zip", "title": null, "favicon": null } [/block] then please install Rublon Two Factor Authentication plugin from Atlassian Marketplace available at: [block:embed] { "html": false, "url": "https://marketplace.atlassian.com/plugins/com.rublon.jira.plugins.twofactorauthentication/server/overview", "title": "Rublon Two-Factor Authentication", "favicon": "https://marketplace-cdn.atlassian.com/s/528/images/favicon.ico", "image": "https://marketplace-cdn.atlassian.com/files/images/baa24376-f2e5-4070-8aef-040dc8158e6c.jpeg", "iframe": false } [/block] ### Automatic installation To install Rublon Two Factor filter module first you need to locate your JIRA installation top directory. ##### Windows Open INSTALL.cmd file to perform automatic installation. After running the file you will be asked for JIRA location, enter the location you have found earlier and press ENTER. After checking if the path is correct, bash file will search for missing files and copy it to /lib folder. ##### Unix Run INSTALL.sh file to perform automatic installation. After running the file you will be asked for JIRA location, enter the location you have found earlier and press ENTER. After checking if the path is correct, bash file will search for missing files and copy it to /lib folder. ###Manual installation To install Rublon Two Factor plugin for JIRA first you need to locate your JIRA installation top directory. For a further reference let's call it $JIRA_INSTALLATION. 1. Install the Rublon Two-Factor Filter JAR: Copy rublon-2fa-filter.jar and paste it in your lib directory. cp jar/rublon-2fa-filter.jar $JIRA_INSTALLATION/atlassian-jira/WEB-INF/lib 2. Install the Java SDK Rublon JAR: Copy java-rublon-sdk.jar and paste it in your lib directory. cp jar/java-rublon-sdk.jar $JIRA_INSTALLATION/atlassian-jira/WEB-INF/lib 3. Install the JSON JAR: Copy org.json.jar and paste it in your lib directory. cp jar/org.json.jar $JIRA_INSTALLATION/atlassian-jira/WEB-INF/lib 4. **(Recommended)** Compare JIRA /lib directory with /optional_jars directory in installation package. It is recommended to copy every file you are missing. Make sure not to duplicate any of files (even if versions differ). The most common file that may be missing is **httpclient**. [block:callout] { "type": "warning", "body": "If you didn't follow the fourth step and have problems with JIRA, copy the rest of files in /optional_jars directory. Make sure **not to duplicate** any of files (even if versions differ).", "title": "" } [/block] ## Automatic Configuration You can configure you Rublon Two-Factor Authentication plugin using configuration page. In order to do it you need to visit Manage Add-ons section, find Rublon plugin on the list and press the "Configure" button. On the page you will be asked to enter Secret Key and System Token, values you generated earlier in Rublon Developer Area. After entering proper values you have to select "Rublon Two-Factor Authentication" and press the "Save" button. You have to restart your JIRA server for the changes to take effect. ## Manual Configuration If you chose not to configure JIRA using configuration page or encountered any errors during the process, please follow instructions below. Locate web.xml file for your JIRA. It should be located in: $JIRA_INSTALLATION/atlassian-jira/WEB-INF/web.xml Open it and find the following fragment: <filter> <filter-name>security</filter-name> <filter-class>com.atlassian.jira.security.JiraSecurityFilter</filter-class> </filter> Paste the following fragment below: [use correct values for <param-value> of secret.key and system.token (generated in first steps on developers.rublon.com)] <filter> <filter-name>rublon</filter-name> <filter-class>com.rublon.jira.plugins.servlet.filter.RublonAuthenticationFilter</filter-class> <init-param> <param-name>system.token</param-name> <param-value>Enter proper system token value here</param-value> </init-param> <init-param> <param-name>secret.key</param-name> <param-value>Enter proper secret key value here</param-value> </init-param> </filter> Find the following fragment: <filter-mapping> <filter-name>security</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> <dispatcher>FORWARD</dispatcher> <!-- we want security to be applied after urlrewrites, for example --> </filter-mapping> Paste the following fragment below: <filter-mapping> <filter-name>rublon</filter-name> <url-pattern>/*</url-pattern> <dispatcher>FORWARD</dispatcher> <dispatcher>REQUEST</dispatcher> </filter-mapping> You have to restart your JIRA server for the changes to take effect. ## Disabling the plugin You can deactivate the plugin in plugin configuration page by selecting "Default Authentication" instead of "Rublon Two-Factor Authentication". You can also do it manually by taking the following steps: Find filter nodes added earlier: <filter> <filter-name>rublon</filter-name> <filter-class>com.rublon.jira.plugins.servlet.filter.RublonAuthenticationFilter</filter-class> <init-param> <param-name>system.token</param-name> <param-value>Enter proper system token value here</param-value> </init-param> <init-param> <param-name>secret.key</param-name> <param-value>Enter proper secret key value here</param-value> </init-param> </filter> and <filter-mapping> <filter-name>rublon</filter-name> <url-pattern>/*</url-pattern> <dispatcher>FORWARD</dispatcher> <dispatcher>REQUEST</dispatcher> </filter-mapping> Delete both entries or comment them out using following brackets: <!-- entry --> You have to restart your JIRA server for the changes to take effect. ### Optional You can also delete plugin lib files, but it is not recommended to delete files other than rublon-2fa-filter.jar and java-rublon-sdk.jar unless you are sure it is not used by any other plugin. Before deleting any file it is recommended to make a backup copy of potentially unused files. ## Known Issues While trying to login using Dashboard login gadget in JIRA 6 or older you may encounter an error: > Sorry, your username and password are incorrect - please try again. In this case you can try to refresh a website or click Log In button in the top right corner or enter address of login.jsp directly in the address bar. > $HOST/jira/login.jsp It is also possible to force a redirection to login page upon trying to access Dashboard without being logged in. 1. While being logged in as an administrator press "g" button twice to open a search bar 2. Find an Announcement Banner 3. Enter the following JS script <script> if(jQuery('#header-details-user-fullname').text().indexOf(" ") ==-1 && window.location.href.indexOf("/secure/Dashboard.jspa") != -1) { window.location = contextPath+"/login.jsp" } </script> 4. Set visibility level to public and accept changes by clicking on Set Banner button This short script will redirect to login.jsp page whenever unauthenticated user tries to access Dashboard. If logged in user tries to access Dashboard he won't be redirected. You can also disable the login gadget on the Dashboard. 1. Locate you JIRA home directory (it contains dbconfig.xml). 2. Edit jira-config.properties file, if file doesn't exist you should create one. 3. Add the following line to the config file: jira.disable.login.gadget=true 4. Save the edited file. 5. Restart your JIRA server.