Extending RPC Plugin for SSO

Some JIRA customers integrate JIRA with an SSO system. The instructions do not cover the RPC plugin.

To extend the RPC plugin for an SSO solution one needs to have the SSO authenticate the user information (username and password). This can be done by replacing the default TokenManager with your own implementation.

How to Replace the TokenManager

The implementation class which is used to fulfill the TokenManager interface is defined in the atlassian-plugin.xml file distributed in the atlassian-jira-rpc-plugin-x.x.x-x.jar. The definition looks like this:

<component key="tokenManager" i18n-name-key="admin.web.rpc.plugin.token.manager.name" name="Token Manager" class="com.atlassian.jira.rpc.auth.TokenManagerImpl">
    <interface>com.atlassian.jira.rpc.auth.TokenManager</interface>
</component>

You can change the implementation used by changing the class to be the full class name of your implementation in the component XML tag. You must also include the new class file in the atlassian-jira-rpc-plugin-x.x.x-x.jar. If you were to change this to be a class called MyTokenManager in the package my.company.package the component definition would become:

<component key="tokenManager" i18n-name-key="admin.web.rpc.plugin.token.manager.name" name="Token Manager" class="my.company.package.MyTokenManager">
   <interface>com.atlassian.jira.rpc.auth.TokenManager</interface>
</component>

What needs to be done to implement a TokenManager

The TokenManager has a simple interface with 4 methods defined:

1. String login(username, password)
2. boolean logout(token)
3. User retrieveUser(token)
4. User retrieveUserNoPermissionCheck(token)

The login method is where you have the opportunity to validate the username and password against your SSO. This method should generate a unique token that can then be used to lookup a com.opensymphony.user.User object that exists in your JIRA instance (via the retrieveUser or retrieveUserNoPermissionCheck methods). The generated token can be the token that your SSO generates or any other unique identifier. In this method you must keep some mapping between your generated token and username. This can be done by actually keeping track of the token/username mapping or encoding the information into the actual token. This is an implementation detail that is left to the developer. Please do take care to time-out your tokens in some way so that your tokens do not allow endless authentication.

The source for the JIRA RPC plugin is open source and details on how to download the source can be found here For ideas on how to map usernames to tokens and how to generate random tokens please see the code for TokenManagerImpl.

Once the login (authentication) has occurred subsequent calls to either retrieveUser or retrieveUserNoPermissionCheck should return the user object that represents the logged-in user for that token. You can attain this object, once you have resolved the username from the token, via a call like:

User user = UserUtils.getUser(username);

The difference between the retrieveUser and retrieveUserNoPermissionCheck is as the names imply. The retrieveUser method should preform a check to see that the user has the JIRA USE permission, retrieveUserNoPermissionCheck does not check the permission, it simply returns the User object. The permission check can be done with the following code, with access to a PermissionManager:

permissionManager.hasPermission(Permissions.USE, user)

The logout method should make the token invalid.

Please note that these instructions are still only theoretical, we have not tested these approaches.