Simple ejabberd Rest API Configuration¶
Restrict to Local network¶
If you are planning to use ejabberd API for admin purpose, it is often enough to configure it to be available local commands. Access is thus generally limited by IP addresses, either restricted to localhost only, or restricted to one of your platform back-end.
-
Make sure an ejabberd_http listener is using mod_http_api on a given root URL and on a desired port:
The
ip
option ensures it listens only on the local interface (127.0.0.1) instead of listening on all interface (0.0.0.0). -
By defining
api_permissions
, you can then allow HTTP request from a specific IP to trigger API commands execution without user credentials:api_permissions: "API used from localhost allows all calls": who: ip: 127.0.0.1/8 what: - "*" - "!stop" - "!start"
Note: stop and start commands are disabled in that example as they are usually restricted to ejabberdctl command-line tool. They are consider too sensitive to be exposed through API.
-
Now you can query the API, for example:
Encryption¶
If you already defined certificates and your connection is not on a local network, you may want to use encryption.
-
Setup encryption like this:
-
Now you can query using HTTPS:
-
If you are using a self-signed certificate, you can bypass the corresponding error message:
Basic Authentication¶
Quite probably you will want to require authentication to execute API queries, either using basic auth or OAuth.
-
Assuming you have the simple listener:
-
Define an ACL with the account that you will use to authenticate:
-
Allow only that ACL to use the API:
-
If that account does not yet exist, register it:
-
Now, when sending an API query, provide the authentication for that account:
-
Example Python code:
OAuth Authentication¶
Before using OAuth to interact with ejabberd API, you need to configure OAuth support in ejabberd.
Here are example entries to check / change in your ejabberd configuration file:
-
Add a request handler for OAuth:
listen: - # Using a separate port for oauth and API to make it easy to protect it # differently than BOSH and WebSocket HTTP interface. port: 5281 # oauth and API only listen on localhost interface for security reason # You can set ip to 0.0.0.0 to open it widely, but be careful! ip: 127.0.0.1 module: ejabberd_http request_handlers: /api: mod_http_api /oauth: ejabberd_oauth
-
Set the oauth_access top-level option to allow token creation:
-
Define an ACL with the account that you will use to authenticate:
-
You can then configure the OAuth commands you want to expose and who can use them:
-
If that account does not yet exist, register it:
-
Request an authorization token. A quick way is using ejabberdctl:
-
Now, when sending an API query, provide the authentication for that account:
curl -H "Authorization: Bearer erHymcBiT2r0QsuOpDjIrsEvnOS4grkj" \ '127.0.0.1:5281/api/registered_users?host=localhost' ["user2","user8","john"]
Or quite simply: