ms-procs.tcl

Publicity: Public Only All

ms-procs.tcl

Support for the Microsoft Graph API These interface classes support conversion from/to JSON and to the urlencoded calling patterns on the fly, just by specifying the Tcl variable names mith minor annotations (somewhat similar to the export_vars interface). Furthermore, the interface supports pagination: some Microsoft Graph API calls return per default just a partial number of results (e.g. first 100). To obtain all results multiple REST calls have to be issued to get the full result set. Over this interface, one can specify the desired maximum number of entries. To use the Microsoft Graph API, an "app" has to be registered/configured/authorized/...[1,2,3] by an administrator of the organization before an access token [4] can be obtained token from the Microsoft identity platform. The access token contains information about your app and the permissions it has for the resources and APIs available through Microsoft Graph. This Interface is based on access tokens [4] and the /token endpoint [1] ("Get access without a user") and assumes, one has already obtained the client_id and client_secret to configure this service this way. In theory, this API will allow later to switch to newer versions of the Graph API when newer versions (currently post 1.0) of the Microsoft Graph API will come out. See also: https://openacs.org/xowiki/msgraph
This file defines the following Objects and Classes: ::ms::Authorize, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Authorize, ::ms::Authorize, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Authorize, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph, ::ms::Graph

Location:

packages/xooauth/tcl/ms-procs.tcl
Author:

Gustaf Neumann [1] https://docs.microsoft.com/en-us/graph/auth-v2-service [2] https://docs.microsoft.com/en-us/graph/auth/auth-concepts [3] https://docs.microsoft.com/en-us/graph/auth-register-app-v2 [4] https://oauth.net/id-tokens-vs-access-tokens/

Procedures in this file

Class ::ms::Authorize (public)
Class ::ms::Graph (public)
ms::Authorize instproc login_url (public)
ms::Authorize instproc logout (public)
ms::Authorize instproc logout_url (public)
ms::Graph instproc run_donecallback (public)
ms::Graph instproc schedule_donecallback (public)
ms::Graph instproc token (public)
ms::Graph instproc {application get} (public)
ms::Graph instproc {application list} (public)
ms::Graph instproc {chat get} (public)
ms::Graph instproc {chat messages} (public)
ms::Graph instproc {group deleted} (public)
ms::Graph instproc {group get} (public)
ms::Graph instproc {group list} (public)
ms::Graph instproc {group member add} (public)
ms::Graph instproc {group member list} (public)
ms::Graph instproc {group member remove} (public)
ms::Graph instproc {group memberof} (public)
ms::Graph instproc {group owner add} (public)
ms::Graph instproc {group owner list} (public)
ms::Graph instproc {group owner remove} (public)
ms::Graph instproc {team archive} (public)
ms::Graph instproc {team channel list} (public)
ms::Graph instproc {team clone} (public)
ms::Graph instproc {team create} (public)
ms::Graph instproc {team delete} (public)
ms::Graph instproc {team get} (public)
ms::Graph instproc {team member add} (public)
ms::Graph instproc {team member list} (public)
ms::Graph instproc {team member remove} (public)
ms::Graph instproc {team unarchive} (public)
ms::Graph instproc {user get} (public)
ms::Graph instproc {user list} (public)
ms::Graph instproc {user memberof} (public)
ms::Graph instproc {user me} (public)
ms::Graph proc run_donecallback (public)

Detailed information

Class ::ms::Authorize (public)

 ::nx::Class ::ms::Authorize

Support for the Microsoft Microsoft identity platform ID tokens to login/logout via MS Azure accounts. https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens

Testcases:
No testcase defined.

Class ::ms::Graph (public)

 ::nx::Class ::ms::Graph

The "tenant" identifies an organization within azure. One OpenACS installation might talk to different tenants at the same time, in which case multiple instances of the Ms Class (or one of its subclasses) must be created. Possible values for the "tenant" property: - "common": Allows users with both personal Microsoft accounts and work/school accounts from Azure AD to sign into the application. - "organizations": Allows only users with work/school accounts from Azure AD to sign into the application. - "consumers": Allows only users with personal Microsoft accounts (MSA) to sign into the application. - tenant GUID identifier, or friendly domain name of the Azure AD, such as e.g. xxxx.onmicrosoft.com Details: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols

Testcases:
No testcase defined.

ms::Authorize method login_url (public)

 <instance of ms::Authorize> login_url [ -prompt prompt ] \
    [ -return_url return_url ] [ -login_hint login_hint ] \
    [ -domain_hint domain_hint ] [ -code_challenge code_challenge ] \
    [ -code_challenge_method code_challenge_method ]

Returns the URL for logging in "oauth2/authorize" is defined in RFC 6749, but requests for MS id-tokens inversion v1.0 and v2.0 are defined here: https://learn.microsoft.com/en-us/azure/active-directory/develop/id-tokens

Switches:

-prompt (optional)
-return_url (optional)
-login_hint (optional)
-domain_hint (optional)
-code_challenge (optional)
-code_challenge_method (optional)

Testcases:
No testcase defined.

ms::Authorize method logout (public)

 <instance of ms::Authorize> logout

Perform logout operation form MS in the background (i.e. without a redirect).

Testcases:
No testcase defined.

ms::Authorize method logout_url (public)

 <instance of ms::Authorize> logout_url \
    [ -return_url return_url ]

Returns the URL for logging out. After the logout, azure redirects to the given page.

Switches:

-return_url (optional)

Testcases:
No testcase defined.

ms::Graph method run_donecallback (public)

 <instance of ms::Graph> run_donecallback location callback

Method to be finally executes the donecallback. First, we have to check whether the async operation has already finished. If this operation is still in progress, reschedule this operation.

Parameters:

location (required)

callback (required)

Testcases:
No testcase defined.

ms::Graph method schedule_donecallback (public)

 <instance of ms::Graph> schedule_donecallback secs location \
    callback

Add an atjob for the for the done callback. The job is persisted, such that even for long running operations and server restarts, the operation will continue after the server restart.

Parameters:

secs (required)

location (required)

callback (required)

Testcases:
No testcase defined.

ms::Graph method token (public)

 <instance of ms::Graph> token [ -grant_type grant_type ] \
    [ -scope scope ] [ -assertion assertion ] \
    [ -requested_token_use requested_token_use ]

Get bearer token (access token) from the /oauth2/v2.0/token endpoint, with timestamp validation (based on "expires_in") result. Obtaining the access token is MsGraph dependent. Probably, some of this can be factored out later to one of the super classes.

Switches:

-grant_type (optional, defaults to "client_credentials")
-scope (optional, defaults to "https://graph.microsoft.com/.default")
with prefconfigured permissions: use "https://graph.microsoft.com/.default" Comment: This method performs its own caching via nsvs. It would be better to use the ns_cache framework with it's built-in expiration methods via ns_cache_eval, but we get the expiration time provided from the non-cached call and not upfront, before this call. We do not want to use a hack with double ns_cache calls, so we leave this for the time being.
-assertion (optional)
-requested_token_use (optional)

Testcases:
No testcase defined.

ms::Graph method application get (public)

 <instance of ms::Graph> application get [ -select select ] \
    application_id

Get the properties and relationships of an application object. Details: https://docs.microsoft.com/graph/api/application-list

Switches:

-select (optional)
return selected attributes, e.g. id,appId,keyCredentials

Parameters:

application_id (required)

Testcases:
No testcase defined.

ms::Graph method application list (public)

 <instance of ms::Graph> application list [ -count count ] \
    [ -expand expand ] [ -filter filter ] [ -orderby orderby ] \
    [ -search search ] [ -select select ] [ -top top ]

Get the list of applications in this organization. Details: https://docs.microsoft.com/graph/api/application-list

Switches:

-count (optional)
boolean, retrieves the total count of matching resources
-expand (optional)
retrieve related information via navigation property, e.g. members
-filter (optional)
retrieve a filtered subset of the tuples
-orderby (optional)
order tuples by some attribute
-search (optional)
returns results based on search criteria.
-select (optional)
return selected attributes, e.g. id,appId,keyCredentials
-top (optional, integer, accept empty)
sets the page size of results

Testcases:
No testcase defined.

ms::Graph method chat get (public)

 <instance of ms::Graph> chat get chat_id

Retrieve the properties and relationships of user object. Details: https://docs.microsoft.com/en-us/graph/api/chat-get

Parameters:

chat_id (required)

Testcases:
No testcase defined.

ms::Graph method chat messages (public)

 <instance of ms::Graph> chat messages [ -top top ] chat_id

Retrieve the properties and relationships of user object. Details: https://docs.microsoft.com/en-us/graph/api/chat-list-messages

Switches:

-top (optional, integer, accept empty)
sets the page size of results (for chat, max is 50)

Parameters:

chat_id (required)

Testcases:
No testcase defined.

ms::Graph method group deleted (public)

 <instance of ms::Graph> group deleted [ -count count ] \
    [ -expand expand ] [ -filter filter ] [ -orderby orderby ] \
    [ -search search ] [ -select select ] [ -top top ]

List deleted groups. Since groups are large objects, use $select to only get the properties of the group you care about. Details: https://docs.microsoft.com/graph/api/directory-deleteditems-list

Switches:

-count (optional)
boolean, retrieves the total count of matching resources
-expand (optional)
retrieve related information via navigation property, e.g. members
-filter (optional)
retrieve a filtered subset of the tuples
-orderby (optional)
order tuples by some attribute
-search (optional)
returns results based on search criteria.
-select (optional, defaults to "id,displayName,deletedDateTime")
return selected attributes, e.g. id,displayName,userPrincipalName
-top (optional, integer, accept empty)
sets the page size of results

Testcases:
No testcase defined.

ms::Graph method group get (public)

 <instance of ms::Graph> group get [ -select select ] group_id

Get the properties and relationships of a group object. To get properties that are not returned by default, specify them in a -select OData query option. Details: https://docs.microsoft.com/en-us/graph/api/group-get

Switches:

-select (optional)
return selected attributes, e.g. displayName,mail,visibility

Parameters:

group_id (required)

Testcases:
No testcase defined.

ms::Graph method group list (public)

 <instance of ms::Graph> group list [ -count count ] \
    [ -expand expand ] [ -filter filter ] [ -orderby orderby ] \
    [ -search search ] [ -select select ] [ -max_entries max_entries ] \
    [ -top top ]

To get a list of all groups in the organization that have teams, filter by the resourceProvisioningOptions property that contains "Team" (needs beta API): resourceProvisioningOptions/Any(x:x eq 'Team') Otherwise, one has to get the full list and filter manually. Since groups are large objects, use $select to only get the properties of the group you care about. Details: https://docs.microsoft.com/graph/teams-list-all-teams https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter

Switches:

-count (optional)
boolean, retrieves the total count of matching resources
-expand (optional)
retrieve related information via navigation property, e.g. members
-filter (optional)
retrieve a filtered subset of the tuples
-orderby (optional)
order tuples by some attribute
-search (optional)
returns results based on search criteria.
-select (optional, defaults to "id,displayName,userPrincipalName")
return selected attributes, e.g. id,displayName,userPrincipalName
-max_entries (optional)
retrieve this desired number of tuples (potentially multiple API calls)
-top (optional, integer, accept empty)
return up this number of tuples per request (page size)

Testcases:
No testcase defined.

ms::Graph method group member add (public)

 <instance of ms::Graph> group member add group_id principals

Add a conversationMember to a group. Details: https://docs.microsoft.com/en-us/graph/api/group-post-members

Parameters:

group_id (required)

principals (required)

Testcases:
No testcase defined.

ms::Graph method group member list (public)

 <instance of ms::Graph> group member list [ -count count ] \
    [ -filter filter ] [ -search search ] [ -max_entries max_entries ] \
    [ -top top ] group_id

Get a list of the group's direct members. A group can have users, organizational contacts, devices, service principals and other groups as members. Currently service principals are not listed as group members due to staged roll-out of service principals on Graph V1.0 endpoint. Details: https://docs.microsoft.com/en-us/graph/api/group-list-members

Switches:

-count (optional)
boolean, retrieves the total count of matching resources
-filter (optional)
retrieve a filtered subset of the tuples
-search (optional)
returns results based on search criteria.
-max_entries (optional)
retrieve this desired number of tuples (potentially multiple API calls)
-top (optional, integer, accept empty)
sets the page size of results

Parameters:

group_id (required)

Testcases:
No testcase defined.

ms::Graph method group member remove (public)

 <instance of ms::Graph> group member remove group_id principal

Remove group member Details: https://docs.microsoft.com/en-us/graph/api/group-delete-members

Parameters:

group_id (required)

principal (required)

Testcases:
No testcase defined.

ms::Graph method group memberof (public)

 <instance of ms::Graph> group memberof [ -count count ] \
    [ -filter filter ] [ -orderby orderby ] [ -search search ] \
    group_id

Get groups that the group is a direct member of. Details: https://docs.microsoft.com/en-us/graph/api/group-list-memberof

Switches:

-count (optional)
when "true" return just a count
-filter (optional)
filter criterion
-orderby (optional)
sorting criterion, e.g. displayName
-search (optional)
search criterion, e.g. displayName:Video

Parameters:

group_id (required)

Testcases:
No testcase defined.

ms::Graph method group owner add (public)

 <instance of ms::Graph> group owner add group_id principal

add an owner to a group. Details: https://docs.microsoft.com/en-us/graph/api/group-post-owners

Parameters:

group_id (required)

principal (required)

Testcases:
No testcase defined.

ms::Graph method group owner list (public)

 <instance of ms::Graph> group owner list group_id

Retrieve a list of the group's owners. Details: https://docs.microsoft.com/en-us/graph/api/group-list-owners

Parameters:

group_id (required)

Testcases:
No testcase defined.

ms::Graph method group owner remove (public)

 <instance of ms::Graph> group owner remove group_id user_id

Remove group owner Details: https://docs.microsoft.com/en-us/graph/api/group-delete-owners

Parameters:

group_id (required)

user_id (required)

Testcases:
No testcase defined.

ms::Graph method team archive (public)

 <instance of ms::Graph> team archive \
    [ -shouldSetSpoSiteReadOnlyForMembers shouldSetSpoSiteReadOnlyForMembers ] \
    [ -donecallback donecallback ] [ -wait ] team_id

Archive the specified team. When a team is archived, users can no longer send or like messages on any channel in the team, edit the team's name, description, or other settings, or in general make most changes to the team. Membership changes to the team continue to be allowed. Details: https://docs.microsoft.com/en-us/graph/api/team-archive

Switches:

-shouldSetSpoSiteReadOnlyForMembers (optional)
This optional parameter defines whether to set permissions for team members to read-only on the SharePoint Online site associated with the team. Setting it to false or omitting the body altogether will result in this step being skipped.
-donecallback (optional)
cmd to be executed when the async command succeeded or failed. One additional argument is passed to the callback indicating the result status.
-wait (optional, defaults to "false")
when specified, perform up to 10 requests checking the status of the async command

Parameters:

team_id (required)

Testcases:
No testcase defined.

ms::Graph method team channel list (public)

 <instance of ms::Graph> team channel list [ -filter filter ] \
    [ -select select ] [ -expand expand ] team_id

Retrieve the list of channels in this team. Details: https://docs.microsoft.com/en-us/graph/api/channel-list

Switches:

-filter (optional)
retrieve a filtered subset of the tuples, e.g. "membershipType eq 'private'"
-select (optional)
select subset of attributes
-expand (optional)
retrieve related information via navigation property, e.g. members

Parameters:

team_id (required)

Testcases:
No testcase defined.

ms::Graph method team clone (public)

 <instance of ms::Graph> team clone \
    [ -classification classification ] [ -description description ] \
    -displayName displayName  -mailNickname mailNickname  \
    -partsToClone partsToClone  [ -visibility visibility ] \
    [ -donecallback donecallback ] [ -wait ] team_id

Create a copy of a team specified by "team_id". It is possible to copy just some parts of the old team (such as "apps", "channels", "members", "settings", or "tabs", or a comma-separated combination).

Switches:

-classification (optional)
-description (optional)
-displayName (required)
-mailNickname (required)
-partsToClone (required)
specify e.g. as "apps,tabs,settings,channels"
-visibility (optional)
-donecallback (optional)
cmd to be executed when the async command succeeded or failed. One additional argument is passed to the callback indicating the result status. Details: https://docs.microsoft.com/en-us/graph/api/team-clone
-wait (optional, defaults to "false")
when specified, perform up to 10 requests checking the status of the async command

Parameters:

team_id (required)
of the team to be cloned (might be a template)

Testcases:
No testcase defined.

ms::Graph method team create (public)

 <instance of ms::Graph> team create [ -description description ] \
    -displayName displayName  [ -visibility visibility ] -owner owner  \
    [ -donecallback donecallback ] [ -wait ]

Create a new team. A team owner must be provided when creating a team in an application context. Details: https://docs.microsoft.com/en-us/graph/api/team-post

Switches:

-description (optional)
-displayName (required)
-visibility (optional)
-owner (required)
-donecallback (optional)
cmd to be executed when the async command succeeded or failed. One additional argument is passed to the callback indicating the result status.
-wait (optional, defaults to "false")
when specified, perform up to 10 requests checking the status of the async command

Testcases:
No testcase defined.

ms::Graph method team delete (public)

 <instance of ms::Graph> team delete team_id

Delete group/team. When deleted, Microsoft 365 groups are moved to a temporary container and can be restored within 30 days. After that time, they're permanently deleted. Details: https://docs.microsoft.com/en-us/graph/api/group-delete

Parameters:

team_id (required)

Testcases:
No testcase defined.

ms::Graph method team get (public)

 <instance of ms::Graph> team get [ -expand expand ] \
    [ -select select ] team_id

Retrieve the properties and relationships of the specified team. Every team is associated with a group. The group has the same ID as the team - for example, /groups/{id}/team is the same as /teams/{id}. For more information about working with groups and members in teams, Details: https://docs.microsoft.com/en-us/graph/api/team-get

Switches:

-expand (optional)
retrieve related information via navigation property, e.g. members
-select (optional)
select subset of attributes

Parameters:

team_id (required)

Testcases:
No testcase defined.

ms::Graph method team member add (public)

 <instance of ms::Graph> team member add [ -roles roles ] team_id \
    principal

Add a conversationMember to the collection of a team. Details: https://docs.microsoft.com/en-us/graph/api/team-post-members

Switches:

-roles (optional, defaults to "member")

Parameters:

team_id (required)

principal (required)

Testcases:
No testcase defined.

ms::Graph method team member list (public)

 <instance of ms::Graph> team member list [ -filter filter ] \
    [ -select select ] team_id

Get the conversationMember collection of a team. Details: https://docs.microsoft.com/en-us/graph/api/team-list-members

Switches:

-filter (optional)
restrict answers to a subset of tuples, e.g. (microsoft.graph.aadUserConversationMember/displayName eq 'Harry Johnson')
-select (optional)
select subset of attributes

Parameters:

team_id (required)

Testcases:
No testcase defined.

ms::Graph method team member remove (public)

 <instance of ms::Graph> team member remove team_id principal

Remove a conversationMember from a team. Details: https://docs.microsoft.com/en-us/graph/api/group-delete-members

Parameters:

team_id (required)

principal (required)

Testcases:
No testcase defined.

ms::Graph method team unarchive (public)

 <instance of ms::Graph> team unarchive \
    [ -donecallback donecallback ] [ -wait ] team_id

Restore an archived team. This restores users' ability to send messages and edit the team, abiding by tenant and team settings. Teams are archived using the archive API. Details: https://docs.microsoft.com/en-us/graph/api/team-unarchive

Switches:

-donecallback (optional)
cmd to be executed when the async command succeeded or failed. One additional argument is passed to the callback indicating the result status.
-wait (optional, defaults to "false")
when specified, perform up to 10 requests checking the status of the async command

Parameters:

team_id (required)

Testcases:
No testcase defined.

ms::Graph method user get (public)

 <instance of ms::Graph> user get [ -select select ] principal

Retrieve the properties and relationships of user object. Details: https://docs.microsoft.com/en-us/graph/api/user-get

Switches:

-select (optional)
return selected attributes, e.g. displayName,givenName,postalCode

Parameters:

principal (required)

Testcases:
No testcase defined.

ms::Graph method user list (public)

 <instance of ms::Graph> user list [ -select select ] \
    [ -filter filter ] [ -max_entries max_entries ] [ -top top ]

Retrieve the properties and relationships of user object. For the users collection the default page size is 100, the max page size is 999, if you try $top=1000 you'll get an error for invalid page size. Details: https://docs.microsoft.com/en-us/graph/api/user-list

Switches:

-select (optional, defaults to "displayName,userPrincipalName,id")
return selected attributes, e.g. displayName,givenName,postalCode
-filter (optional)
restrict answers to a subset, e.g. "startsWith(displayName,'Neumann')"
-max_entries (optional)
retrieve this desired number of tuples (potentially multiple API calls)
-top (optional, integer, accept empty)
return up this number of tuples per request (page size)

Testcases:
No testcase defined.

ms::Graph method user memberof (public)

 <instance of ms::Graph> user memberof [ -count count ] \
    [ -filter filter ] [ -orderby orderby ] [ -search search ] \
    principal

Get groups, directory roles, and administrative units that the user is a direct member of. Details: https://docs.microsoft.com/en-us/graph/api/user-list-memberof

Switches:

-count (optional)
when "true" return just a count
-filter (optional)
filter criterion
-orderby (optional)
sorting criterion, e.g. displayName
-search (optional)
search criterion, e.g. displayName:Video

Parameters:

principal (required)

Testcases:
No testcase defined.

ms::Graph method user me (public)

 <instance of ms::Graph> user me [ -select select ] \
    [ -token token ]

Retrieve the properties and relationships of the current user identified by the token. The "me" request is only valid with delegated authentication flow. Details: https://docs.microsoft.com/en-us/graph/api/user-get

Switches:

-select (optional)
return selected attributes, e.g. displayName,givenName,postalCode
-token (optional)

Testcases:
No testcase defined.

ms::Graph object method run_donecallback (public)

 ms::Graph run_donecallback serialized_app_obj location callback

Helper method for running callbacks. In general, we cannot rely that the interface object (typically ms::app) exists also in the job-queue, where atjobs are executed. Therefore, the class method receives everything to reconstruct the used interface object.

Parameters:

serialized_app_obj (required)

location (required)

callback (required)

Testcases:
No testcase defined.

[ show source ]