You can authorize a signed-in user to call Microsoft Graph and other APIs from MDriven Turnkey by using the access token and refresh token issued through OpenID Connect.
Use the OpenID Connect token flow
For new solutions, use OpenIdConnect access token and refresh token. This is the generic MDriven approach for calling an API at the same identity provider where the user signed in.
A Microsoft Graph access token is short-lived. A refresh token lets Turnkey obtain a new access token without sending the user through interactive sign-in again. Turnkey stores these tokens as claims on the signed-in user:
| Token | Purpose | Where Turnkey stores it |
|---|---|---|
| Access token | Authorizes a Microsoft Graph request. It is short-lived. | SysUserClaim with ClaimType access_token
|
| Refresh token | Obtains a replacement access token after the access token expires. | SysUserClaim with ClaimType refresh_token
|
Configure OpenID Connect so that Turnkey has the token endpoint and requests the offline_access scope. Azure AD only returns a refresh token when offline_access is included. Set SharedSecret in TurnkeySettings so that temporary tokens stored in the database are encrypted.
Refresh the token before calling an API
Before an operation that needs a current token, call the method on the current SysUser:
OpenIdConnectAccessTokenRefresh():String
The method returns ok or an error. When it returns ok, Turnkey has updated the access_token and refresh_token claims.
For example, your action can refresh first and only continue with the API call when the result is ok. If renewal fails, direct the user to sign in again. A refresh token can be revoked, for example after a long period without use or when Azure AD invalidates it because of an account or security event.
Request only the permissions the user needs
In the Azure app registration, grant the Microsoft Graph permissions required by the operation. For an application that acts on behalf of the signed-in user, use delegated permissions. Delegated permissions mean that Graph evaluates access as the signed-in user; Graph does not return content that the user is not allowed to access.
For example, a document-search solution may request:
offline_access User.Read Sites.Read.All
The scopes are space-delimited. The permissions configured in the app registration and the scopes requested during authorization must support the Graph operations you intend to perform. Microsoft Graph, rather than the older SharePoint API entry, is used for SharePoint access in this scenario.
Configure the Azure app registration
Create or update an app registration in the Azure portal before testing the flow.
- Sign in to Azure portal with an account that can manage the organizationâs app registrations.
- Open App registrations and select the application used by your MDriven solution.
- Record the application (client) ID, tenant ID, and client secret for the MDriven configuration.
- Add every redirect URI where Azure AD is allowed to return after sign-in. Include development, test, and production URLs that you use.
- In the applicationâs API permissions, add the required Microsoft Graph delegated permissions.
- Configure the app so it can return the required tokens for the sign-in flow.
A redirect URI must match the URI sent by the application exactly, including letter case. An incorrect redirect URI prevents Azure AD from returning to the application.
Call Microsoft Graph
After a successful OpenID Connect sign-in and a successful token refresh, use the current userâs access_token as a bearer token in your REST request. For example, the Graph /me endpoint returns information about the signed-in user:
vResult:=selfVM.RestGet('https://graph.microsoft.com/v1.0/me','Bearer',SysSingleton.oclSingleton.CurrentUser.Office365AccessToken,'')
Use this example to verify that authorization and the requested User.Read permission work before adding document, calendar, mail, or directory operations. For REST request patterns and operators, see Documentation:Rest API and Documentation:OCLOperators RestPost.
Legacy Office365-specific configuration
The following configuration describes the earlier Office365-specific flow. Keep it only for an existing solution that already uses these SysSingleton and SysUser attributes. New work should use the generic OpenID Connect token flow above.
Store the Azure registration values
Add the Azure app-registration values to SysSingleton:
| Azure value | MDriven attribute |
|---|---|
| Client ID | SysSingleton.Office365ClientId
|
| Tenant ID | SysSingleton.Office365TennantId
|
| Client secret | SysSingleton.Office365ClientSecret
|
| Redirect URI | SysSingleton.Office365Redirect
|
| Space-delimited scopes | SysSingleton.Office365Scope
|
Set the app registrationâs redirect URI to the exact, case-sensitive value in SysSingleton.Office365Redirect. It must point to:
<your-system-url>/Account/AzureAdAuthorize
The Account/AzureAdAuthorize controller action uses the Office365 values in SysSingleton. It posts to the Azure AD token endpoint and writes the resulting tokens to the current userâs SysUser.Office365AccessToken and SysUser.Office365RefreshToken attributes.
Start authorization in the browser
Authorization must start from a browser navigation because the identity provider needs to present sign-in and password prompts. Build the authorization URL using the tenant ID, client ID, redirect URI, and requested scopes:
'https://login.microsoftonline.com/'+SysSingleton.oclSingleton.Office365TennantId+'/oauth2/v2.0/authorize?
client_id='+SysSingleton.oclSingleton.Office365ClientId+'
&response_type=code
&redirect_uri='+SysSingleton.oclSingleton.UrlEncode( SysSingleton.oclSingleton.Office365Redirect,false)+'
&response_mode=query
&scope='+SysSingleton.oclSingleton.UrlEncode( SysSingleton.oclSingleton.Office365Scope,false)+'
&state='+SysSingleton.oclSingleton.UrlEncode('http://localhost:5020/App#/AzureAuthorize/$null$',false)
Azure AD returns a short-lived authorization code to the redirect URI. The controller exchanges that code for an access token and, when offline_access was requested, a refresh token.
The state parameter is returned unchanged by Azure AD. Use it to identify where the application should navigate after authorization. You can expose the authorization URL in a ViewModel column with the DataIsLink tagged value, or navigate to it from an action with selfVM.NavigateURL.
Refresh and use the legacy token
The legacy flow renews the access token with:
SysSingleton.oclSingleton.CurrentUser.Office365RefreshAccessToken;
Then send the current access token as a bearer token, as in the /me example above. Access tokens commonly have a short lifetime; do not assume a token obtained at sign-in remains valid for a later operation.
Microsoft 365 document scenarios
For Microsoft 365 and SharePoint document search, document references, groups, and users, use Documentation:SysGraphAPI. Its model pattern stores encrypted access and refresh tokens in SysToken and refreshes them through SysUser.OpenIdConnectAccessTokenRefresh. Retain document identifiers such as item ID and drive ID when you need to retrieve the associated document or thumbnail later.