AtlasCamp 2014: Building a Connect Add-on With Your Own Stack

June 3-5, 2014 | Berlin, Germany

Patrick Streule, Architect, Atlassian
Build a Connect Add-on
with Your Own Stack

• Atlassian Connect Express: node.js/express
• Atlassian Connect Play: Java/Play
• ACE and AC-Play provide:
• Authentication handling (both directions)
• Lifecycle handling
• Persistence
ACE/AC-Play vs Your Own

• You have an existing service that will host the add-on
• Development in your company happens on a diﬀerent
stack
• Connect does not prescribe a stack at all
ACE/AC-Play vs Your Own

Product
Overview
WEBHOOKS
REST
API
REST API
HTTP
Add-On

Serve descriptor and add-on UI 
☑ Web server / web framework 
☑ SSL certiﬁcate
Handle add-on installation 
☑ Persistent store
Handle add-on requests 
☑ JWT token handler 
☑ Crypto library 
☑ JSON and HttpClient libs
Checklist

• Description of the Add-On
• Where does it show up?
• Where are the add-on
endpoints?
• General Metadata
The Descriptor
{!
"key": "atlas-camp",!
"name": "AtlasCamp",!
"baseUrl": “https://addon.example.com”,!
"authentication": {!
"type": "none"!
},!
"modules": {!
"generalPages": [!
{!
"url": "/intro.html",!
"key": "intro-page",!
"name": {!
"value": "Atlas Camp"!
}!
}!
]!
}!
}

The Content
<!DOCTYPE html>!
<html>!
<head>!
<title>Atlas Camp</title>!
<script src=“https://someinstance.jira.com/atlassian-connect/all.js”></script>!
! <style>body { text-align: center; padding-top: 50px; }</style>!
</head>!
<body>!
<div class=“ac-content”>!
<a href=“https://www.atlassian.com/atlascamp/2014">!
! <img src=“img/atlas-camp.png"/>!
</a>!
</div>!
</body>!
</html>

• HTTPS in production, HTTP for development only
• Include all.js from the host:
The Important Bits
var hostBaseUrl = getUrlParameter("xdm_e");!
var contextPath = getUrlParameter("cp");!
loadScript(hostBaseUrl + contextPath + "/atlassian-connect/all.js");

Adding Authentication:
Installation Event

• Authentication type: JWT
• Installed Lifecycle hook is
required.
• Will be called during
installation
• Other hooks:
• Uninstalled, Enabled, Disabled
!
Setting it up
{!
"key": "atlas-camp",!
"name": "AtlasCamp",!
"baseUrl": “https://addon.example.com”,!
"authentication": {!
"type": "jwt"!
},!
"lifecycle": {!
"installed": "/installed",!
"uninstalled": "/uninstalled"!
}!
}

Installation event
• clientKey 
Identiﬁes the tenant
• sharedSecret 
The key for signing
and verifying JWT
tokens
• baseUrl 
The host and context
path of the product

• Authenticity
• Parties are who they claim to be
• Integrity
• The request was not tampered with
• Authorization (special case in Connect)
• User has access to the pages and issues referenced by URL
parameters
JWT

JWT: Anatomy of a token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiO
jE0MDEwODEwMzgsInN1YiI6ImZmODA4MTgxNDBjMDcyOWE
wMTQwY2Q0NWE5MWQwMDBkIiwiaXNzIjoiQ29uZmx1ZW5jZ
TowNzA3MjM3MjM2IiwicXNoIjoiMjU5YzZkNjU1NjEwYzg
yNzE3MDMxNWEwMTM1ZGI0OTAwODYxZjkxYzA5NDdlM2I2N
jY2NjgyZTkzMDU1NWFiNCIsImlhdCI6MTQwMTA4MDg1OH0
.iSmtl3ukm8EohrCwO94MF7sXeEFtIRQ-aBggghjlE0E

Header
Payload,
Claims
Signature

{"alg":"HS256","typ":"JWT"}
{!
"exp": 1401081038,!
"sub": “ff808…d000d”,!
"iss": "Confluence:070789",!
"qsh": “259c6…55ab4”,!
"iat": 1401080858!
}
HMAC
using SHA-256
Expires
at
Subject
Issuer
Query
String
Hash Issued
at
BTW: Never rely
on this preﬁx!

JWT Verification: Step 1
base64url(sign(‘eyJhbGciOiJIUzI1NiIsInR5cCI6Ik
pXVCJ9.eyJleHAiOjE0MDEwODEwMzgsInN1YiI6ImZmODA
4MTgxNDBjMDcyOWEwMTQwY2Q0NWE5MWQwMDBkIiwiaXNzI
joiQ29uZmx1ZW5jZTowNzA3MjM3MjM2IiwicXNoIjoiMjU
5YzZkNjU1NjEwYzgyNzE3MDMxNWEwMTM1ZGI0OTAwODYxZ
jkxYzA5NDdlM2I2NjY2NjgyZTkzMDU1NWFiNCIsImlhdCI
6MTQwMTA4MDg1OH0’,  
header.alg, tenants[claims.iss].sharedSecret))!
!
== iSmtl3ukm8EohrCwO94MF7sXeEFtIRQ-aBggghjlE0E ?

JWT Verification: Step 2
a=5,7&lic=none&page.id=19809&user_id=pstreule
{!
"baseUrl": “https://addon.example.com/base”,…!
}
GET /base/render?page.id=19809&a=7&a=5&user_id=pstreule&lic=none&jwt=eY…
"qsh": “259c6…55ab4”
hex(sha256(‘GET&…’))
remove context path remove ‘jwt’, order keys and values, apply OAuth1 encoding rulesuppercase
/renderGET &&

• Characters in the unreserved character set MUST NOT
be encoded: (ALPHA, DIGIT, "-", ".", "_", "~")
• All other characters MUST be encoded
• The two hexadecimal characters  
used to represent encoded characters  
MUST be uppercase.
Pitfalls
Raw Encoded
SPACE %20
* %2A
! %21
' %27
( %28
) %29

• JWT tokens used on incoming and outgoing requests
• URL Parameter: jwt=eY…
• HTTP header: Authorization: JWT eY…
• Find more information
• http://go.atlassian.com/ac-docs
• http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html
JWT Summary

Adding Authentication:
Add-On to Add-On

• Do not use session cookies
• Cookies set by the iframe are third-party cookies
• Many browsers don’t accept them by default
Pitfalls

• How to handle authentication for intra-add-on Ajax calls
and links.
Your own requests

• Create a JWT token for the tenant and user
• QSH is optional, depending on the parameter data
Reuse JWT
{!
"exp": 1401081038,!
"sub": “ff808…d000d”,!
"iss": "Confluence:070789",!
"iat": 1401080858!
}

Quick descriptor deployment
curl -i -X HEAD -u admin:admin  
http://localhost:2990/jira/rest/plugins/1.0/
HTTP/1.1 200 OK!
upm-token: 7864481825707347853
curl -i -X POST -u admin:admin !
-H "Content-type: application/vnd.atl.plugins.remote.install+json"  
-d '{"pluginUri":"http://localhost:3000/atlassian-connect.json"}'!
http://localhost:2990/jira/rest/plugins/1.0/?token=7864481825707347853

We’re here to help 
http://go.atlassian.com/ac-dev

AtlasCamp 2014: Building a Connect Add-on With Your Own Stack

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à AtlasCamp 2014: Building a Connect Add-on With Your Own Stack

Similaire à AtlasCamp 2014: Building a Connect Add-on With Your Own Stack (20)

Plus de Atlassian

Plus de Atlassian (20)

Dernier

Dernier (20)

AtlasCamp 2014: Building a Connect Add-on With Your Own Stack