Document how to trigger auth client popup with www-authenticate to OCS API (OC-RequestAppPassword)

[mrow4a]

WHAT Needs to be Documented?

https://github.com/owncloud/core/pull/38486 https://github.com/owncloud/enterprise/issues/4196

WHERE Does This Need To Be Documented (Link)?

user manual (I think)

WHY Should This Change Be Made?

to allow users use authentication popup window in various clients e.g. Excel/Browser to authenticate to OCS API

(Optional) What Type Of Content Change Is This?

• [x] New Content Addition
• [ ] Old Content Deprecation
• [ ] Existing Content Simplification
• [ ] Bug Fix to Existing Content

(Optional) Which Manual Does This Relate To?

• [ ] Admin Manual
• [ ] Developer Manual
• [x] User Manual
• [ ] Android
• [ ] iOS
• [ ] Branded Clients
• [ ] Desktop Client
• [ ] Other

Doc contents

Issue

Before owncloud 10 (seems also oc10.5) one could request password window asking username:password browsing to URL https://whatever/remote.php/dav/files/whateveruser/whatever

This behavior got depreciated in oc10

Web Browser using Headers Extensions

This method levarages adding to browser custom header using e.g. Chrome ModHeader Extension

1. Try accessing API in web browser, it will fail

2. Create APP Password in ownCloud personal settings

3. Add header OC-RequestAppPassword to indicate we want to request interactive app password authentication

4. Authenticate using created app password and enjoy

Excel

Sub owncloud()

    Range("A1").Interior.Color = vbRed
    Dim oXHTTP As Object
    Set oXHTTP = CreateObject("MSXML2.ServerXMLHTTP")
    
    With oXHTTP
        .Open "GET", "http://owncloudURL/ocs/v1.php/apps/files_sharing/api/v1/shares", False
        .setRequestHeader "OC-RequestAppPassword", "true"
        .send
    End With
    
End Sub

Javascript

Using https://github.com/owncloud/owncloud-sdk

I cannot get around problem with CORS on code in [1]. However, there is another way with using owncloud-sdk. This snippet should work but did not test as this would require me to build brand new dev environment and application, effort is pretty high (I am not JavaScript expert...)

const owncloud = require('owncloud-sdk');
let oc = new owncloud({
      baseUrl: owncloudURL,
      headers: {
        "OC-RequestAppPassword": "true"
      }
});

// Login with User and defined App Password with popup window
oc.login().then(status => {
    // STUFF
}).catch(error => {
    // HANDLE ERROR
});

// List all files for the user that authenticated with app password 
oc.files.list('/path/to/file/folder').then(files => {
    console.log(files);
}).catch(error => {
    console.log(error);
});

[1]

import '[email protected]'
import $ from 'jquery'

$('button')
  .html('Click me')
  .on('click', () => {
    $.ajax({
            url: "http://localhost:8000/ocs/v1.php/apps/files_sharing/api/v1/shares",
            type : "GET",
            headers: {  
              "OCS-APIREQUEST": true,
              "OC-RequestAppPassword": "true",
            },
            tls : {
              validate: false
            },
            mode: 'cors',
            data: null,
            action: 'user',
            success: function(result) {
              console.log('ok');
            },
            error: function(result) {
              console.log('error');
            }
     });
  })

console.log('App started')

[mrow4a]

@mmattel I might need help on where to place this content. Any ideas?

[pmaier1]

user manual (I think)

Sounds more like dev docs to me. @mmattel, please go ahead and find a good spot.

[mmattel]

I had an intensive and productive call today with @mrow4a. The best location will be the user manual in subsection integration. Just need a go to proceed.

[pmaier1]

Ok, if you think that's the right spot, go for it.

[mrow4a]

@mmattel any progress? do you need any clarifications?

[mrow4a]

@mmattel as discussed I attempted demo.

[mrow4a]

@mmattel is the provided info enough?

[mrow4a]

updated documentation content in top post