fschade commented 3 years ago

WHAT Needs to be Documented?

How to integrate ownCloud 10 into MSTeams

WHERE Does This Need To Be Documented (Link)?

https://doc.owncloud.com/server/latest/admin_manual/configuration/integration/microsoft-teams

WHY Should This Change Be Made?

No changes, we need to document a new feature which shows how to use ownCloud from within teams

(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?

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

todos

[ ] check, if admins can predefine apps for specific users
[ ] MS Teams Bridge: update link to documentation in info.xml
[ ] evaluate: how to make it more easy for admins to update the .htaccess (occ and config.php) within an update of ownCloud
[ ] Azure-Button Label "Login to ownCloud"
[ ] Add bridge-app description here: https://github.com/owncloud/core/blob/master/config/config.apps.sample.php

Input for Doc's Team

with 10.7 we created a few tools and updated some code from ownCloud to make it able to be displayed and be used from within MSTeams.

Use cases

access your private or organizations ownCloud installation from your existing MSTeams account. The clue here is that expect others we decided to create a generator that creates a customized MSTeams AppSource App for your individual ownCloud installation hosted on your private domain. That's something that differentiate our solution from others.

Configuration

Overall we have 3 parties that needed to be configured to get it up and running.

MSAzure AD
- here we need to setup a custom app that is needed for openidconnect
ownCloud
- openidconnect 2.0.0 app github (it has a own README with useful tips), marketplace
- NEW: msteamsbridge 1.0.0 app github (it has a own README with useful tips), marketplace coming soon.
MSTeams
app that is generated by msteamsgen

Azure (same setup applies to openidconnect app)

( please extend the OICD Doc with Azure as follows: )

Login to Azure
GoTo Manage Azure Active Directory
Then go to "app registrations" and click new registration
provide all required information there
GoTo Authentication and setup your redirect url
GoTo Certificates & secrets and setup a Client secret for your app
GoTo token configuration and setup the claims
GoTo API permissions and add following delegated graph permissions
At the same page please do not forget to grant admin consent to all permissions
GoTo "Expose an API" and set Application ID URI
Then on the same page add a scope with name "owncloud" and allow admins and users to consent
You get the CLIENT-ID after you've completed the MS Azure Setup process

ownCloud

install ownCloud
install openidconnect 2.0.0 app
install msteamsbridge 1.0.0 app
enable rewrites (e.g. apache mod_rewrite) /index.php/foo/bar => /foo/bar (see index_php_less_urls)

apply the following header configuration (ownCloud .htaccess):

Header add Content-Security-Policy "frame-ancestors teams.microsoft.com *.teams.microsoft.com"

apply the required ownCloud configuration with above values from azure for openid-connect and set samesite cookie to 'None'


<?php
$CONFIG = [
'http.cookie.samesite' => 'None',
'openid-connect' => [
    'provider-url' => 'https://login.microsoftonline.com/YOUR-DIRECTORY-TENANT-ID/v2.0/',
    'client-id' => 'YOUR-CLIENT-ID',
    'client-secret' => 'YOUR-CLIENT-SECRET',
    'loginButtonName' => 'Azure AD',
    'autoRedirectOnLoginPage' => false,
    'scopes' => [
        'openid',
        'api://YAOR-APPLICATION-ID-SCOPE-URI/owncloud',
        'profile', 'email', 'offline_access',
    ],
    'mode' => 'email',
    'search-attribute' => 'unique_name',
    'use-access-token-payload-for-user-info' => true,
    'auto-provision' => [
        'enabled' => true,
        'email-claim' => 'email',
        'display-name-claim' => 'email',
    ],
],
];


### MS Teams (as Admin )
- In MS Teams AppSource: search for "ownCloud Generator for Admins" and open the Application
- once opened, please follow the guided steps.
- hint: name your App eg. "ownCloud for Teams"
- all steps are described on top of every step, the id MUST be the [APLLICATION-ID](https://gist.githubusercontent.com/fschade/c6647ed1b8a0c1349bbaac962322fd4a/raw/6eb955f428c375c39e4170d0a89ca09c68f2cf8a/msteams_11.png) from AZURE and the [url](https://gist.githubusercontent.com/fschade/c6647ed1b8a0c1349bbaac962322fd4a/raw/6eb955f428c375c39e4170d0a89ca09c68f2cf8a/msteams_12.png) MUST be your private owncloud installation url
- after all steps are finished press the download button and keep the generated zip file locally
- go back to the app section of MSTeams again and [upload](https://gist.githubusercontent.com/fschade/c6647ed1b8a0c1349bbaac962322fd4a/raw/633382d4ee7f5e9a65d5ec3ede0839124b389e2f/msteams_13.png) the generated zip from the step before 
- after this is done, upload the resulting zip file to your company's AppSource
- MS docs about upload apps to the AppSource Store: https://docs.microsoft.com/en-us/microsoftteams/manage-apps and: https://docs.microsoft.com/en-us/microsoftteams/upload-custom-apps
- (check, if admins can predefine apps for specific users )

### MS Teams (as consuming user)
- login to [MSTeams](https://teams.microsoft.com/)
- search for our app "ownCloud for Teams" (or the name provided by your Admin)
- hint: you can pin the app to your left sidebar permanently: rightclick -> pin
![image](https://user-images.githubusercontent.com/26610733/113852868-4d736580-979d-11eb-9cf6-bb34ff8e0d7d.png)
- login by clicking "Login to ownCloud with Azure AD"
- for security reasons you have to repeat the login process after idle time

## Support
- supply contact infos for help ( support@owncloud.com, central.owncloud.com )

As for the submission in AppSource, Microsoft requires from us to offer contact information for support. This is a requirement. lets discuss how we can integrate this requirement in our processes / oc-universe.
![image](https://user-images.githubusercontent.com/26610733/113829446-ce266780-9785-11eb-88ce-aa8756bba37e.png)

ChrisEdS commented 3 years ago

Do we need single quotes? For example

        'auto-provision' => [
            'enabled' => true,
            'email-claim' => 'email',
            'display-name-claim' => 'email',
        ],

and

      "openid-connect" => [
        "provider-url" => "https://login.microsoftonline.com/YOUR-DIRECTORY-TENANT-ID/v2.0/",
        "client-id" => "YOUR-CLIENT-ID",
        "client-secret" => "YOUR-CLIENT-SECRET",
        "loginButtonName" => "Azure AD",
        "autoRedirectOnLoginPage" => false,
        "scopes" => [
            "openid",
            "api://YAOR-APPLICATION-ID-SCOPE-URI/owncloud",
            "profile", "email", "offline_access",
     ],

looks inconsistent.

fschade commented 3 years ago

Do we need single quotes? For example

        'auto-provision' => [
            'enabled' => true,
            'email-claim' => 'email',
            'display-name-claim' => 'email',
        ],

and

      "openid-connect" => [
        "provider-url" => "https://login.microsoftonline.com/YOUR-DIRECTORY-TENANT-ID/v2.0/",
        "client-id" => "YOUR-CLIENT-ID",
        "client-secret" => "YOUR-CLIENT-SECRET",
        "loginButtonName" => "Azure AD",
        "autoRedirectOnLoginPage" => false,
        "scopes" => [
            "openid",
            "api://YAOR-APPLICATION-ID-SCOPE-URI/owncloud",
            "profile", "email", "offline_access",
     ],

looks inconsistent.

good catch, done. I think it's finally time to convert the draft into a real thing. @pmaier1 any concerns?

fschade commented 3 years ago

@tbsbdr, can you double check aboves howTo please. for example we mention that the app is called "ownCloud generator for Teams" but i do not know the final name which we submitted to the appsource store.

tbsbdr commented 3 years ago

ownCloud generator for Teams

"ownCloud for Teams" is the submitted name in the appsource store. corrected it in the description above.

fschade commented 3 years ago

@tbsbdr, @pmaier1 i removed draft state, in my opinion we are good to start documenting this.

tbsbdr commented 3 years ago

@fschade as discussed, could you please update / add:

[ ] Azure-Button Label "Login to ownCloud with Azure AD"
[ ] Add bridge-app description here: https://github.com/owncloud/core/blob/master/config/config.apps.sample.php (See the rules adding a config key)

pmaier1 commented 3 years ago

Azure-Button Label "Login to ownCloud"

@tbsbdr @fschade Just a hint: I think it is possible that users do not need to click the button by setting autoRedirectOnLoginPage to true in the OIDC config (https://doc.owncloud.com/server/admin_manual/configuration/user/oidc/#list-of-openid-connect-config-php-parameters). Does that work in our scenario and should we recommend it?

fschade commented 3 years ago

Azure-Button Label "Login to ownCloud"

@tbsbdr @fschade Just a hint: I think it is possible that users do not need to click the button by setting autoRedirectOnLoginPage to true in the OIDC config (https://doc.owncloud.com/server/admin_manual/configuration/user/oidc/#list-of-openid-connect-config-php-parameters). Does that work in our scenario and should we recommend it?

please do not use redirect, as we are using teams sdk a real user interaction should happen.

https://docs.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/auth-tab-aad#initiate-authentication-flow

... Authentication flow should be triggered by a user action. You should not open the authentication pop-up automatically because this is likely to trigger the browser's pop-up blocker as well as confuse the user. ...

pmaier1 commented 3 years ago

Looking at https://github.com/owncloud/docs/pull/3467 I think we need to update the doc links in the msteamsbridge info.xml and anywhere else where it's used. @tbsbdr FYI

https://github.com/owncloud/msteamsbridge/pull/18

owncloud / docs

Document how to Integrate ownCloud into MS-Teams #3387

WHAT Needs to be Documented?

WHERE Does This Need To Be Documented (Link)?

WHY Should This Change Be Made?

(Optional) What Type Of Content Change Is This?

(Optional) Which Manual Does This Relate To?

todos

Input for Doc's Team

Use cases

Configuration

Azure (same setup applies to openidconnect app)

ownCloud