Wiki source code of Extend JIRA Authentication
Last modified by Vincent Massol on 2026/08/04 21:49
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{version product="JIRA" since="11.0.0"}} | ||
| 2 | The authentication schemes offered when an administrator defines a JIRA instance are pluggable: the extension ships "No authentication" and "Basic auth", and a new scheme adds itself to that list. A scheme has two halves that are tied together by a single identifier: a user interface extension contributing the fields the administrator fills, and a Java Component signing the requests with them. The Basic authentication scheme is the working example to copy, its user interface under {{scm user="xwiki-contrib" project="jira" path="jira-config/jira-config-ui/src/main/resources/JIRA/JIRAAuth"}}JIRA.JIRAAuth{{/scm}} and its Component at {{scm user="xwiki-contrib" project="jira" path="jira-config/jira-config-platform/src/main/java/org/xwiki/contrib/jira/config/internal/BasicAuthJIRAAuthenticatorFactory.java"}}BasicAuthJIRAAuthenticatorFactory{{/scm}}. | ||
| 3 | |||
| 4 | 1. Choose the identifier of your scheme, which will tie its two halves together, for example ##oauth##. | ||
| 5 | 1. Create a page holding an ##XWiki.UIExtensionClass## xobject whose "Extension Point ID" is ##org.xwiki.contrib.jira.authconfig##, whose "Extension Scope" is ##wiki##, and whose name is unique among the schemes. | ||
| 6 | 1. Set the three parameters of that user interface extension.((( | ||
| 7 | |=Parameter|=Value | ||
| 8 | |##config_id##|The identifier you chose. | ||
| 9 | |##translation_key##|The translation key of the name shown in the "Authentication type" field. | ||
| 10 | |##config_displayer_reference##|The reference of the page displaying your scheme's own fields under "Authentication system configuration". | ||
| 11 | ))) | ||
| 12 | 1. Create the page named by ##config_displayer_reference##, displaying one form field per piece of information your scheme needs, and an XClass to store them keyed by the instance id. | ||
| 13 | 1. Add the translation of ##translation_key## to a translation bundle of your extension. | ||
| 14 | 1. Write a Java Component implementing ##org.xwiki.contrib.jira.config.JIRAAuthenticatorFactory##, annotated ##@Named## with the identifier you chose, whose ##get(String serverId)## method reads the stored configuration of that instance and returns a ##JIRAAuthenticator##, or throws ##JIRAAuthenticatorException## when it cannot. | ||
| 15 | 1. Implement the four methods of ##org.xwiki.contrib.jira.config.JIRAAuthenticator##.((( | ||
| 16 | |=Method|=Returns | ||
| 17 | |##getRestClientAuthenticationHandler()##|The ##AuthenticationHandler## the JIRA Scripting API passes to Atlassian's client. | ||
| 18 | |##authenticateInHttpClient(context, request, targetHost)##|Nothing; it signs the HttpClient request the Macros use, for instance by adding a header. | ||
| 19 | |##isAuthenticatingRequest()##|Whether requests really are authenticated, which lets callers tell a configured scheme from an inert one. | ||
| 20 | |##getId()##|A value identifying this authentication, used to build the cache key of asynchronous Macro rendering. Make it differ whenever the resulting rights differ. | ||
| 21 | ))) | ||
| 22 | 1. Install your extension, then select your scheme in the "Authentication type" field of a JIRA instance definition. Its fields appear, and issues are returned through it. | ||
| 23 | {{/version}} |
