projectdoc Toolbox

Space shortcuts

Page tree

projectdoc Toolbox


REST Login to Confluence with cURL

To access Confluence via its REST API with cURL you typically need to authenticate. Learn how to login with cURL and avoid some common security pitfalls.

Parent
Tips
Audience
Author, Documentation Architect, Documentation Gardener
Level of Experience
Advanced Beginner
Expected Duration
15 min
Tags
Type
Tip



Contents

The Confluence Server REST API can be used with the REST API Browser when it is enabled / installed and when you are logged in to Confluence with your browser. But when you would like to execute REST API calls via cURL (a command-line tool for transferring data using various protocols) you have to login via cURL to use most resources of the Confluence REST API.

This tip shows you how to login to Confluence using cURL.

Prerequisites

Download and Install cURL:

https://curl.haxx.se/download.html

Or install direct e.g in ubuntu:

apt-get install curl

Test your Installation:

curl --version
curl 7.47.0 ...

Executing REST calls

Suppose you want to make some REST calls to your Confluence installation: e.g. https://www.example.com/confluence/rest/api

REST Call with Username and Password

According to the Confluence REST API Examples you could pass the credentials (username and password) directly to cURL for each call:

Simple REST call (login username:password)
curl -u admin:admin https://www.example.com/confluence/rest/api/content/
 

This is very easy and straight forward, but its not very secure, as every one can see your password in plaintext in your console and by listing the running processes by e.g. ps -aux

user@smartics ~ # ps aux | grep curl
user 17637 0.1 0.0 16560 3200 pts/2 S+ 00:09 0:00 curl -u admin:admin https://www.example.com/confluence/rest/api/content/
user 17660 0.0 0.0 9252 2048 pts/3 S+ 00:09 0:00 grep curl

REST Call (Password will be prompted for)

Another option is to enter the password each time you make a REST call by omitting the password in your call:

Simple REST call (login username | password will be prompted)
curl -u admin https://www.example.com/confluence/rest/api/content/
Enter host password for user 'admin':

Now cURL prompts for the password and you can enter it unseen for others. The downside using this is you have to enter the password for every REST call again and again.

WARNING MESSAGE

 

The following two solutions have one thing in common:

They store your password in the file system .

This is on the one hand very convenient but on the other hand a security risk that is discussed widely in the internet: e.g. is-it-safe-to-use-netrc-files-to-store-credentials-for-tools-like-curl-or-ftp.

(warning) So please note: We only show some options to automate REST calls to your Confluence instance. Please ask your system administrator whether or not it is OK to use them!

REST Call using Config File for Credentials

Creating the cURL config file:

Creating the config file
echo "--user admin:XXXX" > ~/curl-password-config.config
chmod go-r ~/curl-password-config.config

Have a look at your file:

The config file
cat ~/curl-password-config.config
--user admin:XXXX

Now edit the file and replace the XXXX placeholder with your password.

Use the config file for your next REST call:

Simple REST call (using config file)
curl --config ~/curl-password-config.config https://www.example.com/confluence/rest/api/content/
 

Everyone who as access to your config file knows your password!

user@smartics ~ # ll ~/curl-password-config.config

-rw-r--r-- 1 user user 427 Jun 19 22:05 curl-password-config.config

So at least secure the file by removing the read access for others and groups. e.g.:

chmod go-r ~/curl-password-config.config

REST Call using .netrc for Credentials

For more information on the .netrc file please read the GNU Documentation on the .netrc file.

 Creating the .netrc file | adding a new machine to the .netrc file:

Creating the .netrc file
echo -e "machine www.example.com \n\tlogin admin\n\tpassword XXXX" >> ~/.netrc
chmod go-r ~/.netrc

Have a look at your file:

The config file
cat ~/.netrc
machine www.example.com
        login admin
        password XXXX

Now edit the file and replace the XXXX placeholder with your password.

Use the .netrc file for your next REST call:

Simple REST call (using config file)
curl -n https://www.example.com/confluence/rest/api/content/
 

Everyone who as access to your .netrc file knows your password!

user@smartics ~ # ll ~/.netrc
-rw-r--r-- 1 user user 427 Jun 19 22:05 .netrc

So at least secure the file by removing the read access for others and groups. e.g.:

chmod go-r ~/.netrc

REST Call using a Session Cookie

One more option you could use is to login to Confluence once, use cookies, store the session cookie and re-use this session cookie for subsequent calls (at least until the session timeout fires):

Login and store session cookie
curl -s --cookie ~/privatedir/confluence.cookie --cookie-jar ~/privatedir/confluence.cookie \
 --data "os_username=admin"  --data "os_password=admin" \
 --data "formname=loginform" --data "login='Log In'" https://www.example.com/confluence/dologin.action -o /dev/null

Now make some REST calls using the cookie:

Simple REST call using session cookie
curl  -s --cookie ~/privatedir/confluence.cookie https://www.example.com/confluence/rest/api/content/
 

Everyone who as access to your session cookie now can execute REST calls on behalf of you or use the cookie in his browser on behalf of you! So it is VERY important to keep the cookie file (/privatedir/confluence.cookie) private!

The default is that the file is created with read access to everyone:

user@smartics ~ # ll ~/privatedir/
-rw-r--r-- 1 user user 427 Jun 19 22:05 confluence.cookie

So at least secure the file by removing the read access for others and groups. e.g.:

chmod go-r ~/privatedir/confluence.cookie

REST Call using a Session Cookie by creating a Config File on the Fly

But there is (at least) one more option you could use. The option to build a config file on the fly, read it from STDIN, read the password from STDIN and use session cookies can be combined efficiently:

Login and store session cookie by creating a config file on the fly
{ echo -n  '--data "os_password='; read a && echo -n $a ; echo -n '"'; } | curl -K - \
 -s --cookie ~/privatedir/confluence.cookie --cookie-jar ~/privatedir/confluence.cookie \
 --data "os_username=admin" \
 --data "formname=loginform" --data "login='Log In'" \ 
 https://www.example.com/confluence/dologin.action -o /dev/null
 

The advantage over the other options is, that using this approach the password is not stored in the file system and afaik   it can not be seen in the process list ( ps -efa or others).

Note: After entering the command above the command does not return but waits for your password to be entered and sent to cURL by pressinf enter.

It works by building the --data "os_password=password" part of the options passed to cURL on the fly and by reading the password from STDIN.

Now make some REST calls using the cookie:

Simple REST call using session cookie
curl  -s --cookie ~/privatedir/confluence.cookie https://www.example.com/confluence/rest/api/content/
 

Everyone who as access to your session cookie now can execute REST calls on behalf of you or use the cookie in his browser on behalf of you! So it is VERY important to keep the cookie file (/privatedir/confluence.cookie) private!

The default is that the file is created with read access to everyone:

user@smartics ~ # ll ~/privatedir/
-rw-r--r-- 1 user user 427 Jun 19 22:05 confluence.cookie

So at least secure the file by removing the read access for others and groups. e.g.:

chmod go-r ~/privatedir/confluence.cookie

References


About

This site is maintained by smartics.

Imprint / Impressum

Data Privacy / Datenschutz 

End User License Agreement (EULA)


To get in touch please send us an e-mail!

smartics email

Keep up-to-date!

Read our

smartics Blog

Follow us on

Twitter YouTube Prezi

Find us on

Bitbucket GitHub Atlassian Marketplace

Powered by




© 2001-2023 smartics - Kronseder & Reiner GmbH