Skip to content

pawelniewie/atlassian-jwt-authentication

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Atlassian JWT Authentication

Atlassian JWT Authentication provides support for handling JWT authentication as required by Atlassian when building add-ons: https://developer.atlassian.com/static/connect/docs/latest/concepts/authentication.html

Installation

From Git

You can check out the latest source from git:

git clone https://github.com/MeisterLabs/atlassian-jwt-authentication.git

Or, if you're using Bundler, just add the following to your Gemfile:

gem 'atlassian-jwt-authentication', 
  git: 'https://github.com/MeisterLabs/atlassian-jwt-authentication.git'

Usage

Setup

This gem relies on the jwt_tokens table being present in your database and the associated JwtToken model.

To create those simply use the provided generators:

bundle exec rails g atlassian_jwt_authentication:setup

If you are using another database for the JWT data storage than the default one, pass the name of the DB config to the generator:

bundle exec rails g atlassian_jwt_authentication:setup shared

Don't forget to run your migrations now!

Controller filters

The gem provides 2 endpoints for an Atlassian add-on lifecycle, installed and uninstalled. For more information on the available Atlassian lifecycle callbacks visit https://developer.atlassian.com/static/connect/docs/latest/modules/lifecycle.html.

If your add-on baseUrl is not your application root URL then include the following configuration for the context path. This is needed in the query hash string validation step of verifying the JWT:

# In the add-on descriptor:
# "baseUrl": "https://www.example.com/atlassian/confluence",

AtlassianJwtAuthentication.context_path = '/atlassian/confluence'

Add-on installation

The gem will take care of setting up the necessary JWT tokens upon add-on installation and to delete the appropriate tokens upon un-installation. To use this functionality, simply call

include AtlassianJwtAuthentication

before_action :on_add_on_installed, only: [:installed]
before_action :on_add_on_uninstalled, only: [:uninstalled]

Add-on authentication

Furthermore, protect the methods that will be JWT aware by using the gem's JWT token verification filter. You need to pass your add-on descriptor so that the appropriate JWT shared secret can be identified:

include AtlassianJwtAuthentication

# will respond with head(:unauthorized) if verification fails
before_filter only: [:display, :editor] do |controller|
  controller.send(:verify_jwt, 'your-add-on-key')
end

Methods that are protected by the verify_jwt filter also give access to information about the current JWT token instance and logged in account (when available):

  • current_jwt_token returns JwtToken
  • current_account_id returns String

Furthermore, this information is stored in the session so you will have access to these 2 instances also on subsequent requests even if they are not JWT signed.

# current_jwt_token returns an instance of JwtToken, so you have access to the fields described above
pp current_jwt_token.addon_key
pp current_jwt_token.base_url

If you need detailed user information you need to obtain it from the instance and process it respecting GDPR.

Add-on licensing

If your add-on has a licensing model you can use the ensure_license filter to check for a valid license. As with the verify_jwt filter, this simply responds with an unauthorized header if there is no valid license for the installation.

before_filter :ensure_license

If your add-on was for free and you're just adding licensing now, you can specify the version at which you started charging, ie. the minimum version of the add-on for which you require a valid license. Simply include the code below with your version string in the controller that includes the other add-on code.

def min_licensing_version
  Gem::Version.new('1.0.0')
end

Middleware

You can use a middleware to verify JWT tokens (for example in Rails application.rb):

config.middleware.insert_after ActionDispatch::Session::CookieStore, AtlassianJwtAuthentication::Middleware::VerifyJwtToken, 'your_addon_key'

Token will be taken from params or Authorization header, if it's verified successfully request will have following headers set:

  • atlassian_jwt_authorization.jwt_token JwtToken instance
  • atlassian_jwt_authorization.account_id String instance
  • atlassian_jwt_authorization.context Hash instance

Middleware will not block requests with invalid or missing JWT tokens, you need to use another layer for that.

Making a service call

Build the URL required to make a service call with the rest_api_url helper or make a service call with the rest_api_call helper that will handle the request for you. Both require the method and the endpoint that you need to access:

# Get available project types
url = rest_api_url(:get, '/rest/api/2/project/type')
response = Faraday.get(url)

# Create an issue
data = {
    fields: {
        project: {
            'id': 10100
        },
        summary: 'This is an issue summary',
        issuetype: {
            id: 10200
        }
    }
}

response = rest_api_call(:post, '/rest/api/2/issue', data)
pp response.success?

User impersonification

To make requests on user's behalf add act_as_user in scopes required by your app.

Later you can obtain OAuth bearer token from Atlassian.

Do that using AtlassianJwtAuthentication::UserBearerToken.user_bearer_token(account_id, scopes)

Logging

If you want to debug the JWT verification define a logger in the controller where you're including AtlassianJwtAuthentication:

def logger
  Logger.new("#{Rails.root}/log/atlassian_jwt.log")
end

Custom error handling

If you want to render your own pages when the add-on throws one of the following errors:

  • forbidden
  • unauthorized
  • payment_required

overwrite the following methods in your controller:

def render_forbidden
  # do your own handling there
  # render your own template 
  render(template: '...', layout: '...')
end

# the same for render_payment_required and render_unauthorized

Installing the add-on

You can use rake tasks to simplify plugin installation:

bin/rails atlassian:install[prefix,email,api_token,https://external.address.to/descriptor]

Where prefix is your instance name before .atlassian.net. You an get an API token from Manage your account page.

Configuration

Config Environment variable Description Default
AtlassianJwtAuthentication.context_path none server path your app is running at ''
AtlassianJwtAuthentication.verify_jwt_expiration JWT_VERIFY_EXPIRATION when false allow expired tokens, speeds up development, especially combined with webpack hot module reloading true
AtlassianJwtAuthentication.log_requests AJA_LOG_REQUESTS when true outgoing HTTP requests will be logged false
AtlassianJwtAuthentication.debug_requests AJA_DEBUG_REQUESTS when true HTTP requests will include body content, implicitly turns on log_requests false

Requirements

Ruby 2.0+, ActiveRecord 4.1+

Integrations

Message Bus

With middleware enabled you can use following configuration to limit access to message bus per user / instance:

MessageBus.user_id_lookup do |env|
  env.try(:[], 'atlassian_jwt_authentication.account_id')
end

MessageBus.site_id_lookup do |env|
  env.try(:[], 'atlassian_jwt_authentication.jwt_token').try(:id)
end

Then use MessageBus.publish('/test', 'message', site_id: X, user_ids: [Y]) to publish message only for a user.

Requires message_bus patch available at https://github.com/HeroCoders/message_bus/commit/cd7c752fe85a17f7e54aa950a94d7c6378a55ed1

Upgrade guide

Version 0.7.x

Removed current_jwt_user, JwtUser, update your code to use current_account_id

Versions < 0.6.x

current_jwt_auth has been renamed to current_jwt_token to match model name. Either mass rename or add alias in your controller:

alias_method :current_jwt_auth, :current_jwt_token
helper_method :current_jwt_auth

Releases

No releases published

Packages

No packages published

Languages

  • Ruby 96.9%
  • HTML 3.1%