Nosy Pinocchio Manners

    @3fv/atlassian-oauth-connect
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.10 • Public • Published

    Atlassian OAuth 2 (3LO) Browser/Server Client

    Install

    It's a properly configured hybrid module, so both commonjs & module/esm runtimes are supported, which means that both browser & node environments can you the entire library excluding the decode functionality, which I'll eventually convert for browser support using cryptojs, but it's transparently functional in any evironment now

    yarn add @3fv/atlassian-oauth-connect

    Example Implementation (not for prod use)

    Prequistes

    First, make sure you've got direnv installed via your package manager of choice brew, apt, pacman, etc...

    Setup

    Copy .envrc.templace to .envrc and fill in all the missing fields. Also, the scope list is robust, but the purpose is to show near every currently available scope, so, go ahead and pair it down to what you need.

    Populate your redirect URI, client id, and client secret with the values you entered/received Atlassian Developer Console when your configured your app

    WARNING: As mentioned, this is just an example; in a real world scenario the configuration would come from another system like AWS AppConfig with appropriate secret management, etc.

    First, copy the file: cp .envrc.template .envrc

    Next, populate your app's values from the aforementioned Atlassian Developer Console App Registration.

    # IN CASE YOUR SHELL DOESN'T DO THIS FOR YOU
    PATH_add $PWD/node_modules/.bin
    
    # SCOPES FOR AUTHORIZATION.
    # THEY MUST BE SPACE DELIMITED
    export ATLASSIAN_SCOPE="\
      read:me \
      offline_access \
      read:jira-user \
      read:jira-work \
      write:jira-work \
      manage:jira-project \
      manage:jira-configuration \
      manage:jira-webhook \
      read:confluence-content.all \
      read:confluence-content.summary \
      write:confluence-content \
      write:confluence-space \
      write:confluence-file \
      read:confluence-props \
      write:confluence-props \
      manage:confluence-project \
      manage:confluence-configuration \
      search:confluence"
    
    # APP REGISTRATION DETAILS
    export ATLASSIAN_REDIRECT_URI=<YOUR_ATLASSIAN_REDIRECT_URI>
    export ATLASSIAN_CLIENT_ID=<YOUR_ATLASSIAN_CLIENT_ID>
    export ATLASSIAN_CLIENT_SECRET=<YOUR_ATLASSIAN_CLIENT_SECRET>

    Run the example

    The example server is a very basic html page and express web server that together function as a fairly complete tooling for testing & verifyingthe atlassian connect integration.

    The source is here ./src/example/server.ts & ./src/example/index.html

    # Install Deps
    yarn
    
    # Build & Run Example Server
    yarn example:server:start
    

    Now you can open a browser to http://localhost:4000 and play around

    Hackup to play with Atlassian Connect

    I figured you'd probably get annoyed if this wasn't easy, so it's all scripted

    To start up the typescript compiler in watch mode and server via nodemon, just run the following

    yarn run example:server:dev

    Features

    • getAccessibleResources() queries for all resources (projects & spaces) for which a user accepted grants. Here's an example response.
    [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "url": "https://3fv.atlassian.net",
        "name": "3fv",
        "scopes": [
          "manage:confluence-configuration",
          "search:confluence",
          "write:confluence-props",
          "read:confluence-props",
          "write:confluence-file",
          "write:confluence-space",
          "write:confluence-content",
          "read:confluence-content.summary",
          "read:confluence-content.all"
        ],
        "avatarUrl": "https://site-admin-avatar-cdn.prod.public.atl-paas.net/avatars/240/triangle.png"
      },
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "url": "https://3fv.atlassian.net",
        "name": "3fv",
        "scopes": [
          "manage:jira-configuration",
          "manage:jira-project",
          "manage:jira-webhook",
          "write:jira-work",
          "read:jira-work",
          "read:jira-user"
        ],
        "avatarUrl": "https://site-admin-avatar-cdn.prod.public.atl-paas.net/avatars/240/triangle.png"
      }
    ]
    • retrieveAccessToken() for code to token exchange

    • getUserProfile() to retrieve the current user profile.

    {
      "account_id": "0000000000000",
      "email": "aaaa@bbbbbbbb.com",
      "name": "Jonathan Glanz",
      "picture": "https://secure.gravatar.com/avatar/...",
      "account_status": "active",
      "last_updated": "2021-11-15T14:49:38.747Z",
      "nickname": "Jonathan Glanz",
      "locale": "en-US",
      "extended_profile": {
        "job_title": "Software Engineer",
        "team_type": "Software Development"
      },
      "account_type": "atlassian",
      "email_verified": true
    }
    • Token refresh rolling functionality; all the requirements to implement refresh token rolling, including the actual refresh token (if you specified the offline_access scope) & the expiration data, so you can implement your own refresh token rolling or wait for me to find a reason 😁

    Todo

    • [ ] Signature Verification (OOB the atlassian-jwt package chucks errors when verifying the returned tokens)
    • [ ] Caching, right now, if you call getUserProfile, retrieveAccessToken, etc., every call no matter identical params or not, query the endpoints; so this is kind of important
    • [ ] Unit tests would be a good idea (started & configured, just not implemented 😄)
    • [ ] Plus a few e2e cypress tests (started)

    Credit

    Written with love in #NYC by @jglanz 3FV. Enjoy

    Install

    npm i @3fv/atlassian-oauth-connect

    DownloadsWeekly Downloads

    10

    Version

    1.0.10

    License

    MIT

    Unpacked Size

    25.4 kB

    Total Files

    18

    Last publish

    Collaborators

    • jglanz