Authentication Document & Microflow Activity (Beta)

content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/integration-activities/_index.md

@@ -23,6 +23,8 @@ The following are the integration activities you can use in your microflow:
 * [Export Mapping](/refguide/export-mapping-action/) – exports data from objects into XML or JSON documents, or a string variable
 * [Query External Database](/refguide/query-external-database/) – uses preconfigured database queries and displays retrieved data 
 * [Send REST Request (beta)](/refguide/send-rest-request/) – sends a REST request 
+* [Authentication (Beta)](/refguide/authentication-action/) – uses preconfigured authentication document and returns the resulting credential
+* [Send Email](/refguide/send-email-action/) – sends an email directly from a microflow
 
 ## Read More
 

content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/activities/integration-activities/authentication-action.md

@@ -0,0 +1,66 @@
+---
+title: "Authentication (Beta)"
+url: /refguide/authentication-action/
+weight: 30
+description: "Describes the configuration items of the Authentication microflow activity in Studio Pro."
+#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details.
+---
+
+{{% alert color="info" %}}
+This activity can only be used in microflows.
+{{% /alert %}}
+
+{{% alert color="info" %}}
+This activity is currently in beta. For more information, see [Release Status](/releasenotes/release-status/).
+{{% /alert %}}
+
+## Introduction
+
+The **Authentication** activity allows you to run the authentication that is configured in an [authentication document](/refguide/authentication/) from a microflow, and to get the result in a variable.
+
+## Properties
+
+The **Authentication** activity properties pane consists of the following sections:
+
+* [Action](#action)
+* [Common](#common)
+
+## Action Section {#action}
+
+The **Action** section of the properties pane shows the action associated with this activity.
+
+You can open a dialog box to configure this action by clicking the ellipsis (**…**) next to the action.
+
+The dialog box consists of the following sections:
+
+* [Authentication document](#authentication-document)
+* [Output](#output)
+
+### Authentication Document {#authentication-document}
+
+The **Authentication document** section contains the **Document** property. Click the selector to choose the [authentication document](/refguide/authentication/) that the activity uses. You can clear the selection by choosing **None**, but a document must be selected for the activity to work.
+
+### Output {#output}
+
+The **Output** section configures the result of the activity.
+
+#### Type
+
+The type of the result. This is `System.Credentials` when an authentication document is selected, and `Nothing` when no document is selected. This property is read-only.
+
+#### Variable Name
+
+The name of the variable that stores the result. The name must be a valid name.
+
+By default, the variable name is `Credentials` when you select an authentication document, and `None` when no document is selected. The name updates automatically until you edit it manually. After that, it keeps the name you entered.
+
+When you change the variable name and click **OK**, Studio Pro renames the variable everywhere it is used in the microflow.
+
+## Common Section {#common}
+
+{{% snippet file="/static/_includes/refguide/microflow-common-section-link.md" %}}
+
+## Read More
+
+* [Authentication](/refguide/authentication/)
+* [Integration Activities](/refguide/integration-activities/)

content/en/docs/refguide/modeling/integration/_index.md

@@ -39,4 +39,8 @@ The following services require you to download an external module from the Mendi
 
 In addition to the integration capabilities available in the Studio Pro, Mendix also supports integration with external systems through RapidMiner Graph Studio. The RapidMiner Graph Studio provides a scalable environment for connecting, managing, and analyzing graph-based data. For more information, see [Integrating Mendix with RapidMiner Graph Studio](/refguide/graph-studio/).
 
+## Authenticating with External Services
+
+To authenticate with external services, you can use an authentication document (beta). An authentication document lets you define the authentication method and credentials once, and reuse them in your microflows, for example with the [Authentication](/refguide/authentication-action/) and [Send Email](/refguide/send-email-action/) activities. Basic and OAuth 2.0 / Entra ID (Client Credentials) authentication are supported. For more information, see [Authentication](/refguide/authentication/).
+
 ## Documents in This Category

content/en/docs/refguide/modeling/integration/authentication.md

@@ -0,0 +1,118 @@
+---
+title: "Authentication (Beta)"
+url: /refguide/authentication/
+weight: 6
+description: "Describes how to use an authentication document to define authentication once and reuse it in your app."
+#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details.
+---
+
+{{% alert color="info" %}}
+This feature is currently in beta. For more information, see [Release Status](/releasenotes/release-status/).
+{{% /alert %}}
+
+## Introduction
+
+An authentication document defines how your app authenticates with an external service. You configure the authentication method and its credentials once in the document, and then reuse the document wherever your app needs to authenticate. Activities that use the document only reference it, and the document manages obtaining the credentials.
+
+An authentication document supports the following authentication methods:
+
+* **Basic** – authenticates with a username and a password
+* **OAuth 2.0 / Entra ID** – authenticates with the OAuth 2.0 Client Credentials grant, for example with Microsoft Entra ID
+
+Each document uses exactly one authentication method.
+
+## Adding an Authentication Document
+
+An authentication document is a type of document you can add to modules in your app. Each document contains a single authentication configuration.
+
+To add an authentication document, do the following:
+
+1. Right-click your module or a folder within a module.
+2. Select **Add other** > **Authentication (Beta)**.
+3. Give your authentication document a name and click **OK**.
+
+The name of the document is the name of the authentication configuration.
+
+Default: *Authentication*
+
+## Defining an Authentication Document {#authentication-document}
+
+To define an authentication document, open it. The authentication is defined in the **Authentication** tab.
+
+### General {#general}
+
+#### Authentication Method
+
+The **Authentication method** determines how your app authenticates with the external service. The following methods are available:
+
+| Authentication method | Description |
+| --- | --- |
+| (none) *(default)* | No authentication method is selected. |
+| Basic | Authenticates with a username and a password. For more information, see [Basic](#basic). |
+| OAuth 2.0 / Entra ID | Authenticates with the OAuth 2.0 Client Credentials grant. For more information, see [OAuth 2.0 / Entra ID](#oauth). |
+
+When you change the authentication method, the values of the previous method are discarded and the properties of the new method are empty.
+
+### Credentials Stored in Constants {#constants}
+
+Sensitive values are not entered directly in an authentication document. Instead, each sensitive property refers to a [constant](/refguide/constants/) that holds the value. This way, you can set a different value for each environment, and you do not need to store secrets in your app model.
+
+For each sensitive property, do the following:
+
+1. Create a constant of type **String**. Mendix recommends not exposing the constant to the client.
+2. In the authentication document, click the selector next to the property and select the constant.
+3. Set the value of the constant. For example, set its [Default Value](/refguide/constants/#default-value) for local development, and set a different value for each environment in the Mendix Portal.
+
+For more information on setting constant values per environment, see the [Constants](/developerportal/deploy/environments-details/#constants) section in *Environment Details*.
+
+A property that does not refer to a constant shows **(none)**.
+
+### Basic {#basic}
+
+When you select the **Basic** authentication method, the **Credentials** section is shown. It has the following properties:
+
+| Property | Description |
+| --- | --- |
+| Username | The constant that holds the username. |
+| Password | The constant that holds the password. |
+
+### OAuth 2.0 / Entra ID {#oauth}
+
+When you select the **OAuth 2.0 / Entra ID** authentication method, the **OAuth Configuration** section is shown. It has the following properties:
+
+| Property | Description | Stored in a constant? | Required? |
+| --- | --- | :---: | :---: |
+| Grant Type | The OAuth 2.0 grant type that is used to obtain the access token. Currently, only **Client Credentials** is supported. | - | - |
+| Access Token URL | The URL of the token endpoint of the identity provider. | Yes | Yes |
+| Client Id | The ID of the client application that is registered with the identity provider. | Yes | Yes |
+| Client Secret | The secret of the client application that is registered with the identity provider. | Yes | Yes |
+| Tenant Id | The ID of the tenant of the identity provider, for example, your Microsoft Entra ID tenant. | Yes | Yes |
+| Scope | The scopes that are requested for the access token. Use comma-separated values, for example, *email, profile*. | No | No |
+| Audience | The intended recipient of the access token, for example, `api://my-api`. | No | No |
+
+If a required property does not refer to a constant, Studio Pro shows a [consistency error](/refguide/consistency-errors/).
+
+#### Check Connection {#check-connection}
+
+Click **Check Connection** to verify that your app can obtain an access token with the configured settings. To check the connection, do the following:
+
+1. Set the values of the constants that the document refers to.
+2. Run your app locally.
+3. Click **Check Connection**.
+
+{{% alert color="info" %}}
+**Check Connection** is only available for the **OAuth 2.0 / Entra ID** authentication method. For the **Basic** method, the credentials are only validated by the external service when a request is made.
+{{% /alert %}}
+
+## Using an Authentication Document {#using}
+
+You can use an authentication document in the following places:
+
+* The [Authentication](/refguide/authentication-action/) microflow activity – runs the authentication that is configured in the document, and returns the result as a `System.Credentials` object that you can use in the rest of the microflow
+* The [Send Email](/refguide/send-email-action/) microflow activity – uses the document to authenticate with the email server when you select **Use Authentication Document**
+
+## Read More
+
+* [Authentication Activity](/refguide/authentication-action/)
+* [Integration Activities](/refguide/integration-activities/)
+* [Constants](/refguide/constants/)