How to use the provisioning API

ℹ️ Support
1

Hi All,

I’m new to linux, new to web servers, and a total ignorant about how to use the provisioning API. I have successfully setup Nextcloud and been loving it but I’d love to be able to use the provisioning API to add/edit users. I’ve read the documentation but I clearly do not understand it. Does anyone have any idea where I could find a how-to that is detailed enough for even a total newbie to use? I’m trying to learn but not much out there to help me out so hoping someone in the community has somewhere to point me.

2

In the documentation, you can even find an example:
https://docs.nextcloud.com/server/9.0/admin_manual/configuration_user/user_provisioning_api.html

Not really sure what you are missing or what you want to do. Can you explain?

3

Yeah I saw the examples, but not sure how to test them out. Do these just plug into as a URL? I can’t imagine it’s that easy and when I tried, it failed, even using the correct login/password.

4

For example, do I use the login/password for the admin account of NextCloud? Or do I need to use the login/password for the MySQL instance (they are different). Or maybe I need to use login credentials for my Ubuntu user account?

5

POST http://admin:secret@example.com/ocs/…

Is there a more secure method than using a user/pass in plaintext over HTTP?

6

I tried using HTTPS and HTTP (local installation) and neither method worked for me.

When I try https://login:password@ipaddress/ocs/v1.php/cloud/users -d userid=“Frank” -d password=“frankspassword” as a test, I get a “Invalid query, please check the syntax. API specifications are here: http://www.freedesktop.org/wiki/Specifications/open-collaboration-services. DEBUG OUTPUT:” error

When I try https://login:password@ipaddress/ocs/v1.php/cloud/users?search=[user_name] I get a “Access forbidden. CSRF check failed” error.

7

And what does “All calls to OCS endpoints require the OCS-APIRequest header to be set to true.” mean? Where is this set?

8

I managed to run it on an old OC 9.0:
curl -X POST -F 'userid=test' -F 'password=test' https://admin:adminpw@example.net/owncloud/ocs/v1.php/cloud/users

1 Like
9

I’m assuming you’re running this via ssh (sorry if this sounds stupid but totally new at this)?

When I run it from terminal I get the {“message”:“CSRF check failed”} error.

Any thoughts on where to go from here?

10

Indeed, let’s ask @LukasReschke

edit: Didn’t try it myself, but you need to get the CSRF token first:
http://tech.saigonist.com/b/code/how-login-any-website-using-curl-command-line-or-shell-script

But it would be nice to have a little snippet in the documentation as well.

11

If I’m reading this page right (http://tech.saigonist.com/b/code/how-login-any-website-using-curl-command-line-or-shell-script) then this is only needed if authentication can’t be sent via the URL, but according to the documentation “Authentication is done by sending a Basic HTTP Authorization header”.

Interestingly enough, when I view source on the page, I can clearly see the data-requesttoken= and its value and something else called requesttoken= and its value.

If it helps, these are the log records associated with my last attempt…

{“reqId”:“mqHkfb2WD04IphGGhVOm”,“remoteAddr”:“192.168.1.1”,“app”:“admin_audit”,“message”:“Login attempt: “redacted””,“level”:1,“time”:“2016-12-14T22:40:20+00:00”,“method”:“GET”,“url”:"/ocs/v1.php/cloud/users/testuser",“user”:"–",“version”:“11.0.0.10”}

{“reqId”:“mqHkfb2WD04IphGGhVOm”,“remoteAddr”:“192.168.1.1”,“app”:“admin_audit”,“message”:“Login successful: “redacted””,“level”:1,“time”:“2016-12-14T22:40:20+00:00”,“method”:“GET”,“url”:"/ocs/v1.php/cloud/users/testuser",“user”:“redacted”,“version”:“11.0.0.10”}

{“reqId”:“mqHkfb2WD04IphGGhVOm”,“remoteAddr”:“192.168.1.1”,“app”:“no app in context”,“message”:“CSRF check failed”,“level”:0,“time”:“2016-12-14T22:40:20+00:00”,“method”:“GET”,“url”:"/ocs/v1.php/cloud/users/testuser",“user”:“redacted”,“version”:“11.0.0.10”}

According to these, the login was successful so at least there’s that.

Something else that may be useful is that I upgraded from v10 to v11 this morning and this is the first time I’ve tried to get a handle on user provisioning via API. The MariaDB was the existing instance from the previous Nextcloud version but everything else seems to be working perfectly so I’m not sure it is related.

12

For my understanding, you need to load the main page of NC first and get the cookie with the CSRF-token, then you just join this information along with your request.

13

The CSRF token isn’t required in those cases as long as you send the OCS-APIRequest: true HTTP header. For example:

➜  stable9 git:(master) ✗ curl http://admin:admin@10.211.55.7/stable9/ocs/v1.php/cloud/users -H "OCS-APIRequest: true"
<?xml version="1.0"?>
<ocs>
 <meta>
  <status>ok</status>
  <statuscode>100</statuscode>
  <message>OK</message>
  <totalitems></totalitems>
  <itemsperpage></itemsperpage>
 </meta>
 <data>
  <users>
   <element>admin</element>
   <element>test</element>
   <element>user01</element>
   <element>user02</element>
  </users>
 </data>

The OCS-APIRequest header is required for security in newer Nextcloud releases.

1 Like
14

Can this API be used without cookies? I’m using Postman for REST API testing, but it doesn’t seem to work due to cookie requirement.

15

I’ve been using the Provisioning API via cli curl, to undertake some basic tasks (update emails, displays names etc), and this has been fine.

I needed to disable a user.

The docs at: https://docs.nextcloud.com/server/11/admin_manual/configuration_user/user_provisioning_api.html#instruction-set-for-users

state the following:
users / disableuser¶

Disables a user on the Nextcloud server so that the user cannot login anymore. Authentication is done by sending a Basic HTTP Authorization header.

Syntax: ocs/v1.php/cloud/users/{userid}/disable

HTTP method: PUT

Statuscodes:

100 - successful
101 - failure

Example

    PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/disable
    Disables the user Frank

I issued the following command:
curl -v -X PUT -H “OCS-APIRequest:true” http://craig:craig@local.nextcloud/ocs/v1.php/cloud/users/test.user/disable

I get the following returned output:

  • Connected to local.nextcloud (127.0.0.1) port 80 (#0)
  • Server auth using Basic with user ‘craig’

PUT /ocs/v1.php/cloud/users/test.user/disable HTTP/1.1
Authorization: Basic Y3JhaWc6Y3JhaWc=
User-Agent: curl/7.35.0
Host: local.nextcloud
Accept: /
OCS-APIRequest:true

< HTTP/1.1 200 OK
< Date: Thu, 16 Mar 2017 20:12:26 GMT

  • Server Apache/2.4.7 (Ubuntu) is not blacklisted
    < Server: Apache/2.4.7 (Ubuntu)
    < Set-Cookie: ocbmh3zryjyj=r4l88h6srffa651atbhvlk7mk7; path=/; HttpOnly
    < Expires: Thu, 19 Nov 1981 08:52:00 GMT
    < Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
    < Pragma: no-cache
    < Set-Cookie: oc_sessionPassphrase=AtNqqJTHiAIVS35UkPgPr%2Bfej%2BYCB%2FQkfIXdBUxFPYnvMw7%2Bl2O%2BQJxK%2BgznOqg3dq2mo%2FwCzVM1FNH9kAtGjwKaw8T5Ls3XFShZU8nio5PKzUO0g6EfYLdzfz%2FCnheJ; path=/; httponly
    < Content-Security-Policy: default-src ‘self’; script-src ‘self’ ‘unsafe-eval’ ‘nonce-bXpNcjFLeTVOYjl6cXBLcWhacjNxcVVRc3FIYlZZM2JQaUdWSElLZkFxRT06ckVkbmtKVFNEUE1hdzlYdzhQVzkyLzFqL05PeEc3dXBjeENpYWRPcGNaYz0=’; style-src ‘self’ ‘unsafe-inline’; frame-src *; img-src * data: blob:; font-src ‘self’ data:; media-src *; connect-src *
    < X-XSS-Protection: 1; mode=block
    < X-Content-Type-Options: nosniff
    < X-Frame-Options: Sameorigin
    < X-Robots-Tag: none
    < X-Download-Options: noopen
    < X-Permitted-Cross-Domain-Policies: none
    < Set-Cookie: nc_sameSiteCookielax=true; path=/; httponly;expires=Fri, 31-Dec-2100 23:59:59 GMT; SameSite=lax
    < Set-Cookie: nc_sameSiteCookiestrict=true; path=/; httponly;expires=Fri, 31-Dec-2100 23:59:59 GMT; SameSite=strict
    < Set-Cookie: ocbmh3zryjyj=o3bvjse8jsqpn1416bkih4h4b6; path=/; HttpOnly
    < Set-Cookie: cookie_test=test; expires=Thu, 16-Mar-2017 21:12:26 GMT; Max-Age=3600
    < Content-Length: 0
    < Content-Type: text/xml; charset=UTF-8
    <
  • Connection #0 to host local.nextcloud left intact

It hasn’t issued the expected xml response and the user isn’t disabled.

Could anyone shed any light on this, offer a solution or advise on possible routes to investigate?

16

So after doing some hunting around in the NC apps provisioning code and using my own PHP test script I discovered a solution for myself regarding the disabling and enabling of NC users via the ProvAPI. I’m posting here in the hope it can help someone else and save them some time.

So the example in the documentation would appear to be missing the (key => value) data submission, the working cli curl command is:

Disable User:
curl -X PUT -H “OCS-APIRequest:true” -v http://admin:secret@example.com/ocs/v1.php/cloud/users/{userid}/disable -d key=“disable” -d value=“true”

Enable User:
curl -X PUT -H “OCS-APIRequest:true” -v http://admin:secret@example.com/ocs/v1.php/cloud/users/{userid}/enable -d key=“enable” -d value=“true”

Could the ProvAPI documentation be updated to reflect the working examples here?