atlassian-crowd-client

atlassian-crowd-client

Promise-based client library to communicate with an Atlassian Crowd server from Node, written in ES6. This uses the Crowd REST APIs.

Installation

npm install --save atlassian-crowd-client

Usage

var CrowdClient = require('atlassian-crowd-client');
var User = require('atlassian-crowd-client/lib/models/user');

// Initialize the Crowd client:
var crowd = new CrowdClient({
  baseUrl: 'https://crowd.example.com/',
  application: {
    name: 'demo',
    password: 'example'
  }
});

// Create a new user:
crowd.user.create(new User('John', 'Doe', 'John Doe', '[e-mail]', 'johndoe', 'secret'));

// Authenticate to Crowd:
crowd.session.create('someusername', 'somepassword').then(function (session) {

  // Fetch the user profile:
  crowd.session.getUser(session.token).then(function (user) {
    console.log('Hello, ' + user.displayname);
  });
});

// Find all active groups (using Crowd Query Language):
crowd.search.group('active=true').then(function (groups) {
  console.log('Found groups: ' + groups.length);
});

Configuration

Refer to the example settings file for all configurable options.

API

The package provides two main classes: CrowdApi and CrowdClient.

The CrowdApi class implements a generic interface to make HTTP requests to the Crowd REST API. It ensures that the appropriate headers are used and errors are handled. It also wraps the callbacks in promises.

The CrowdClient class makes all Crowd REST Resources and their variants/options available as convenient JavaScript methods. Each method provides sensible defaults and maps responses to common domain objects.

Domain model objects

In order to provide a consistent API, most CrowdClient methods map Crowd API responses to domain objects. Many parameters are also expected to be a domain object. Here's an overview of the domain models and their properties:

Session

• token (string): Session token as generated by Crowd.
• createdAt (Date): Creation date/time of the session token.
• expiresAt (Date): Expiration date/time of the session token.

Group

• groupname (string): Name of the group.
• description (string): Description for the group.
• active (boolean): Whether the group is active or not.

User

• firstname (string): First name.
• lastname (string): Last name.
• displayname (string): Display name (i.e. full name).
• email (string): Email address.
• username (string): Username (i.e. login name).
• password (string): Password, only used when creating a new user, never returned by Crowd.
• active (boolean): Whether the user is active or not.

Attributes

• attributes (object): User/Group attributes as key-value pairs.

ValidationFactors

• validationFactors (object): Validation factors as key-value pairs.

Development

The library is completely written in ES6, using babel-node to run tests. Source code is compiled to ES5 before publication to NPM, so the library can also be used in ES5 projects.

Included are integration tests to verify proper functioning of all endpoints. For this you will need to provide settings for a Crowd test server, since the integration tests will make actual HTTP requests. An example settings file is provided at test/helpers/settings-example.js. Copy or rename it to settings.js and provide your own configuration.

git clone https://github.com/wehkamp/atlassian-crowd-client.git
cd atlassian-crowd-client
cp test/helpers/settings-example.js test/helpers/settings.js
npm install
npm test

Changelog

2.0.0 (2017-10-06)

Thanks to Alex Ashley for the original PR.

Breaking

• Changed attributes property on User responses, it is now mapped to an Attributes model.
• Flattened settings object. Update your settings.js accordingly.

Fixed

• attributesParser and attributesEncoder settings are now properly passed along.