OAuth2 User Authorization – a token on behalf of the signed-in user¶

The command "OAuth2 User Authorization" opens the sign-in window of an OAuth2 provider, lets the signed-in user sign in and consent, and writes the resulting token into variables. This page is for administrators who call APIs that must act as the user – for example the mailbox or the files of that user in Microsoft 365.

1. At a glance¶


Purpose	Obtain a delegated access token for the user who runs the action
Typical use	Read the calendar or files of the user through an API that does not accept an application token
Where in the editor	Toolbar menu "UI" → "OAuth2 User Authorization"
Needs a user interface	Yes – not in scheduled actions, background rules, mailbox listeners or REST API calls
Related	OAuth2 Get Token, HTTP Request

Summary¶

A popup window shows the sign-in and consent page of the provider. The provider then sends the browser to the callback page of nexxcite, which hands the answer back to the action.
The redirect address must be https://<address of your nexxcite installation>/oauth2/callback.html and must be registered at the provider exactly like this.
A failure does not stop the action. Check "Has Error Variable" before you use the token.
With "Stay Logged In", the popup only appears again when the stored token can no longer be renewed.

For a token that represents the application rather than a person, use OAuth2 Get Token – it needs no user interface.

2. Settings¶

"Display Name", "Description" and "Execution Condition" are on the tab "General" (see Actions). All text settings are expressions.

Tab "Authorization"¶

Setting	Meaning	Default / Required
"Flow"	`AuthorizationCodeWithPkce` or `Implicit` (see below)	`AuthorizationCodeWithPkce`
"Authorization Endpoint"	Address of the sign-in page of the provider, for example `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize`	Required
"Token Endpoint"	Address of the token endpoint. Only used by `AuthorizationCodeWithPkce`, where it is required.	Required for PKCE
"Redirect Address"	The callback page of this installation: `https://<address>/oauth2/callback.html`	Required
"Scope"	Scopes the user is asked to consent to, separated by spaces	Empty
"Timeout (Seconds)"	How long the user has to sign in and consent	`0` = 5 minutes
"Stay Logged In"	Remembers the authorization for this user (section 3)	Off
"Ignore Certificate Errors"	Accepts an invalid certificate of the token endpoint. Has no effect on the popup, which is the browser of the user.	Off

Tab "Client"¶

Setting	Meaning	Default / Required
"Client Id"	The ID the application is registered under at the provider	Required
"Client Secret"	The secret, for a confidential client. The code is exchanged on the server, so the secret never reaches the browser. Empty for a public client.	Empty

Tab "Additional Parameters"¶

Extra parameters for the sign-in page, each with "Name" and "Value" – for example prompt, login_hint, audience or resource. They are added to the address of the sign-in page only, not to the token request.

Tab "Response"¶

Setting	Receives
"Access Token Variable"	The access token
"Token Type Variable"	The token type, normally `Bearer`
"Expires In Variable"	The lifetime in seconds
"Refresh Token Variable"	The refresh token – only with `AuthorizationCodeWithPkce` and only when the provider returns one (usually with the scope `offline_access`)
"Id Token Variable"	The ID token, when the scope `openid` was requested
"Granted Scope Variable"	The scopes that were actually granted – a user may consent to less than requested
"Has Error Variable"	`true` when no token was obtained
"Error Variable"	The reason

Set at least one of the token variables, otherwise the token is lost.

Flows¶

Value	Meaning
`AuthorizationCodeWithPkce`	The browser only carries a one-time code; the nexxcite server exchanges it for the token. Recommended, and the only flow that can return a refresh token.
`Implicit`	The token itself comes back through the browser. Discouraged by current OAuth2 security recommendations and refused by many providers – only for a legacy provider that offers nothing else.

3. Behaviour¶

Without a user interface the command is skipped.
If "Authorization Endpoint", "Client Id" or "Redirect Address" is empty, the command is skipped and "Has Error Variable" is set to true.
With "Stay Logged In" on and a usable stored token for this user, the token is used and no window opens.
Otherwise a popup window opens with the sign-in page of the provider. The action waits until the provider answers, the user closes the window, or the time runs out.
With AuthorizationCodeWithPkce, the server exchanges the code at "Token Endpoint" for the token.
The variables are written. On any failure the token variables are emptied, "Has Error Variable" is true and "Error Variable" holds the reason. The action continues.

What the user may see¶

Situation	Text in "Error Variable"
The browser blocked the popup	"The browser blocked the authorization window. Allow popups for this application and run the action again."
The user closed the window	"The authorization window was closed before the provider answered."
The time ran out	"The user did not finish the authorization within … seconds."
The user declined or the provider refused	The error of the provider

The window is opened by the server shortly after the click, so strict popup blockers may block it. For productive use, add the nexxcite address to the popup exceptions of the browsers.

Stay Logged In¶

With "Stay Logged In" on, the token is stored per user and never handed to anybody else:

Situation	What happens
The stored access token is valid for more than 2 minutes	It is used without a window
It has expired and a refresh token is stored	It is renewed silently
Renewal fails (password changed, consent withdrawn) or nothing is stored	The window opens again

Request the scope offline_access (or what your provider requires for refresh tokens). Without a refresh token the window comes back as soon as the access token expires. With Implicit there is never a refresh token.

Stored tokens are encrypted in the database with the data protection key of the installation. Without DataProtection:KeyRingPath, they cannot be read after a restart, and users have to sign in again (see Installation and configuration).

4. Examples¶

Read the next appointments of the user from Microsoft Graph.

"OAuth2 User Authorization"
- "Authorization Endpoint" https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize
- "Token Endpoint" https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token
- "Redirect Address" https://nexxcite.contoso.com/oauth2/callback.html
- "Scope" openid offline_access Calendars.Read
- "Client Id" of the app registration, "Stay Logged In" on
- "Access Token Variable" UserToken, "Has Error Variable" AuthFailed, "Error Variable" AuthError
Show Popup with AuthError when AuthFailed is true.
HTTP Request GET https://graph.microsoft.com/v1.0/me/events with header Authorization = Bearer followed by UserToken, only when AuthFailed is false.

Register the redirect address in the app registration at the provider. Which platform type the registration needs is described in the documentation of the provider, which is authoritative. Note that nexxcite exchanges the code on the server, not in the browser.

5. Limitations¶

Needs a user interface.
The token request of the PKCE flow always sends client ID and secret as Basic authentication header (or only the client ID without secret). A provider that expects the secret in the form body cannot be used with a secret here.
In our assessment, the wait for the window can end after about one minute in the current version, even if "Timeout (Seconds)" allows more. Plan for users completing the sign-in within a minute.
There is no command to sign a user out of a stored authorization.
The client secret is an expression of the action or of a global value and is stored readable (see API access and credentials).