Welcome to python-crowd’s documentation!

python-crowd is a python client library to the Atlassian Crowd REST API.

This library may be useful to you if you wish to create an application that authenticates users against Crowd or integrate with Crowd’s SSO.

This project has no official status within Atlassian and is provided as a service to the programming community. I hope that you find it useful.

Documentation

Docs are built automatically by sphinx. You can build them yourself in the doc directory or access them at <http://aelse.github.com/python-crowd/>.

Examples

Some example invocations are provided in the examples directory, and are included in the built documentation.

The unit tests may also be instructive.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Contents:

Indices and tables

• Index
• Module Index
• Search Page

class crowd.CrowdServer(crowd_url, app_name, app_pass)

Crowd server authentication object.

This is a Crowd authentication class to be configured for a particular application (app_name) to authenticate users against a Crowd server (crowd_url).

This module uses the Crowd JSON API for talking to Crowd.

An application account must be configured in the Crowd server and permitted to authenticate users against one or more user directories prior to using this module.

Please see the Crowd documentation for information about configuring additional applications to talk to Crowd.

auth_ping()

Test that application can authenticate to Crowd.

Attempts to authentication the application user against the Crowd server. In order for user authentication to work, an application must be able to authenticate.

Returns:

bool:

True if the application authentication succeeded.

auth_user(username, password)

Authenticate a user account against the Crowd server.

Attempts to authenticate the user against the Crowd server.

Args:

username: The account username.

password: The account password.

Returns:

dict:

A dict mapping of user attributes if the application authentication was successful. See the Crowd documentation for the authoritative list of attributes.

None: If authentication failed.

get_groups(username)

Retrieves a list of group names that have <username> as a direct member.

Returns:

list:

A list of strings of group names.

get_nested_group_users(groupname)

Retrieves a list of all users that directly or indirectly belong to the given groupname.

Args:

groupname: The group name.

Returns:

list:

A list of strings of user names.

get_nested_groups(username)

Retrieve a list of all group names that have <username> as a direct or indirect member.

Args:

username: The account username.

Returns:

list:

A list of strings of group names.

get_session(username, password, remote='127.0.0.1')

Create a session for a user.

Attempts to create a user session on the Crowd server.

Args:

username: The account username.

password: The account password.

remote:

The remote address of the user. This can be used to create multiple concurrent sessions for a user. The host you run this program may need to be configured in Crowd as a trusted proxy for this to work.

Returns:

dict:

A dict mapping of user attributes if the application authentication was successful. See the Crowd documentation for the authoritative list of attributes.

None: If authentication failed.

terminate_session(token)

Terminates the session token, effectively logging out the user from all crowd-enabled services.

Args:

token: The session token.

Returns:

True: If session terminated

None: If session termination failed

user_exists(username)

Determines if the user exists.

Args:

username: The user name.

Returns:

bool:

True if the user exists in the Crowd application.

validate_session(token, remote='127.0.0.1')

Validate a session token.

Validate a previously acquired session token against the Crowd server. This may be a token provided by a user from a http cookie or by some other means.

Args:

token: The session token.

remote: The remote address of the user.

Returns:

dict:

A dict mapping of user attributes if the application authentication was successful. See the Crowd documentation for the authoritative list of attributes.

None: If authentication failed.

Simple Authentication Test

import crowd
import os, sys, getpass

app_url = 'http://my.crowd.server:8095/crowd/'
app_user = 'testapp'
app_pass = 'testpass'

# Create the reusable Crowd object
cs = crowd.CrowdServer(app_url, app_user, app_pass)

if len(sys.argv) > 1:
    username = sys.argv[1]
else:
    username = os.environ['USER']

password = getpass.getpass(prompt='Enter password for %s: ' % username)

success = cs.auth_user(username, password)
if success:
    print 'Successfully authenticated.'
else:
    print 'Failed to authenticate.'

Simple Token Authentication

import crowd
import os, sys, getpass

app_url = 'http://my.crowd.server:8095/crowd/'
app_user = 'testapp'
app_pass = 'testpass'

# Create the reusable Crowd object
cs = crowd.CrowdServer(app_url, app_user, app_pass)

if len(sys.argv) > 1:
    username = sys.argv[1]
else:
    username = os.environ['USER']

password = getpass.getpass(prompt='Enter password for %s: ' % username)

# Create a session. The important bit is the token.
session = cs.get_session(username, password)
if session:
    print 'Created a session, token %s' % session['token']
else:
    print 'Failed to authenticate.'
    sys.exit(1)

# Check that the token is valid (and of course it should be).
success = cs.validate_session(session['token'])
if success:
    print 'Authenticated session token.'
else:
    print 'Failed to authenticate token.'