Feature/add authentication and authorisation documentation to 2025.11 (#253)

Co-authored-by: Donna-Marie Smith <donna.smith@wearecortex.com>

Author: Cortex-DMS

content/en/docs/2025.11/FAQs/configure-oidc-authentication/_index.md

@@ -0,0 +1,6 @@
+---
+title: "How do I configure OpenID Connect authentication?"
+linkTitle: "How do I configure OpenID Connect authentication?"
+description: "Instructions on how to configure OpenID Connect authentication for {{% ctx %}} Gateway."
+weight: 300
+---

content/en/docs/2025.11/FAQs/configure-oidc-authentication/microsoft-entra.md

@@ -0,0 +1,88 @@
+---
+title: "Microsoft Entra"
+linkTitle: "Microsoft Entra"
+description: "Instructions on how to configure Microsoft Entra OIDC Authentication for use in {{% ctx %}} Gateway."
+weight: 1
+---
+
+# {{% param title %}}
+
+## Configure Microsoft Entra OIDC Provider
+
+{{% alert title="Note" %}}
+In order to configure a Microsoft Entra Provider a Microsoft Azure account with at least the `Application Developer` role is needed. A `Workforce` or `External Tenant` is also required.
+{{% /alert %}}
+
+1. Register {{% ctx %}} Gateway as an application to create a trust relationship between {{% ctx %}} Gateway and the Microsoft Identity Platform:
+    1. Login to Microsoft Azure and navigate to `Microsoft Entra ID` > `Manage` > `App registrations`.
+    1. Select `+ New registration`.
+    1. Enter a meaningful Name for the {{% ctx %}} Gateway application.
+    1. Select the appropriate Supported account type, e.g. `Accounts in this organizational directory only`.
+    1. Click `Register`.
+1. Add a Redirect URI to allow {{% ctx %}} Gateway to send log in and log out requests to the Entra endpoint:
+    1. Select the application registration created in Step 1.
+    1. Click `Redirect URIs`.
+    1. Click `+ Add a platform`.
+    1. Select Single-page application and set:
+        * `Redirect URIs` to `<protocol>://<host>:<port>/<webapplicationname>/redirect`, e.g. `https://server.domain.com/gateway/redirect`.
+        * `Front-channel logout URL` to `https://localhost:44321/signout-callback-oidc`.
+        * `Implicit grant and hybrid flows` to `ID tokens`.
+    1. Click `Configure`.
+1. Configure permissions for {{% ctx %}} Gateway to access the user's data using Microsoft Graph:
+    1. Select the application registration created in Step 1.
+    1. Select `API permissions` from the menu on the left.
+        {{% alert title="Note" %}}The Delegated permission `User.Read` was added automatically when the application was registered.{{% /alert %}}
+    1. Click `+ Add a permission`
+        * Select `Microsoft Graph`
+        * Select `Application permissions`.
+        * Locate and expand `GroupMember` and select `GroupMember.Read.All` to allow the application to authenticate itself without user interaction or consent.
+        * Click `Add permissions`.
+    1. Click `+ Add a permission` again.
+        * Select `Microsoft Graph`
+        * Select `Delegated permissions`
+        * Locate and expand `Openid permissions`, and select:
+            * `email` to allow access to view the users’ email address.
+            * `offline_access` to maintain access to data already accessed.
+            * `openid` to allow users to sign in.
+            * `profile` to allow access to view the user’s basic profile.
+        * Click `Add permissions`.
+1. Configure the application registration to return the Entra groups to {{% ctx %}} Gateway:
+    1. Select the application registration created in Step 1.
+    1. Select `Token configuration` from the menu on the left.
+    1. Click `+ Add groups claim`.
+    1. Select `Security groups`.
+    1. Locate and expand `ID`.
+        * Select `sAMAccountName`.
+    1. Click `Add`.
+1. Create credentials for {{% ctx %}} Gateway to authenticate with Entra securely:
+    1. Select the application registration created in Step 1.
+    1. Select `Client credentials`.
+    1. Click `+ New client secret`.
+    1. Enter a `Description` for the client secret.
+    1. In the `Expires` dropdown, select an expiration for the secret or specify a custom lifetime.
+    1. Select `Add`.
+        {{% alert title="Warning" color="warning" %}}Make a note of the client secret Value as this is never displayed again after you have left this page.{{% /alert %}}
+
+## Configure {{% ctx %}} Gateway to use Microsoft Entra Authentication
+
+{{% alert title="Note" %}}
+In order to configure {{% ctx %}} Gateway to use a Microsoft Entra OpenID Connect Provider, an application MUST be registered and configured as specified in {{< ahref path="Cortex.Faqs.ConfigureOidcAuthentication.MicrosoftEntra.Entra" title="Configure Microsoft Entra OIDC Provider" >}}
+{{% /alert %}}
+
+1. Log on to {{% ctx %}} Gateway using the local Administrator account or as a user with the `Admin` role.
+1. Select `Admin` > `Authentication`.
+1. Select the `OpenID Connect` tab.
+1. Click `+ New Provider` and enter the provider details:
+    1. `Identifier` - a unique free-format identifier for this provider. This cannot be edited once the form has been saved.
+    1. `Display Name` - free-format text to be displayed on the provider tab and login button.
+    1. `Authority` - the URL to access the provider authentication. For Microsoft Entra authentication this should be `https://login.microsoftonline.com`.
+    1. `Tenant Identifier` - the Tenant ID. This can be obtained from the Application registration details in Microsoft Entra by clicking on the registration to display its details. Copy the value for `Directory (tenant) ID`.
+    1. `Client Identifier` - the Client ID. This can be obtained from the Application registration details in Microsoft Entra by clicking on the registration to display its details. Copy the value for `Application (client) ID`.
+    1. `Client Secret` - the client secret that was revealed when creating the client credentials for the Application in Microsoft Entra. If you do not have access to the client secret, it will be necessary to create a new client secret in Microsoft Entra - for guidance see step 5 in [Configure Microsoft Entra OIDC][].
+1. Click `Validate` to validate the information entered and enable the Save button.
+    {{% alert title="Note" %}}Validate does not validate the accuracy of the information entered, it only validates that it is of the correct format.{{% /alert %}}
+1. Click `Save` to save the provider’s configuration.
+
+    {{% alert title="Note" %}}It may be necessary to refresh the browser to ensure correct operation.{{% /alert %}}
+
+[Configure Microsoft Entra OIDC]:  {{< url path="Cortex.Faqs.ConfigureOidcAuthentication.MicrosoftEntra.Entra" >}}

content/en/docs/2025.11/Guides/user-guides/user-interfaces/gateway/Admin/Authentication.md

@@ -0,0 +1,101 @@
+---
+title: "Authentication"
+linkTitle: "Authentication"
+description: "Setup authentication providers used to control access to {{% ctx %}} Gateway."
+weight: 20
+---
+
+# {{% param title %}}
+
+## Summary
+
+The Authentication page is used to setup one or more authentication providers used to control access to {{% ctx %}} Gateway.
+
+## Anatomy
+
+Authentication can be configured using [LDAP][] against a Microsoft Active Directory, and [OpenID Connect (OIDC)][OIDC] with one or more providers.
+
+### LDAP
+
+{{< figure src="/images/Authentication - LDAP.png" title="LDAP Authentication Configuration" >}}
+
+LDAP authentication defines the connection to a Microsoft Active Directory server to authorise Active Directory users with different roles and permissions within {{% ctx %}} Gateway.
+
+It requires connection details to the Active Directory server (URL or domain), port and protocol, plus the credentials of an Active Directory account (typically a service account) that can read the Active Directory.
+
+For additional security, and to avoid the clutter of irrelevant information, it is possible to filter the Active Directory information available for use in {{% ctx %}} Gateway to that defined by a set of [Base DNs (Distinguished Names)][DNs].
+
+{{% ctx %}} Roles and Flow Editor permissions can be assigned to groups set up in Active Directory.
+
+The fields available are:
+
+* `Server` – specifies either URL or IPv4 address of the Active Directory server, or the domain name for the Active Directory domain.
+* `Port` – specifies the port used to access Active Directory, typically either 389 for LDAP or 636 for LDAPS.
+* `Use SSL` – a checkbox to connect via the LDAPS protocol rather than LDAP.
+* `Username` – the username of an account with read permissions in Active Directory; typically a service account is used.
+* `Password` – the password associated with the username entered in the `Username` field.
+* `Base DNs` – the Active Directory objects that can be accessed by {{% ctx %}} Gateway. The identity of the objects is expressed using their Distinguished Names. More than one Distinguished Name can be set to refer to multiple objects within the Active Directory. If no Distinguished Names are set, the whole of the Active Directory is accessible.
+
+### OpenID Connect
+
+{{< figure src="/images/Authentication - OIDC.png" title="Open ID Connect Provider Configuration" >}}
+
+OpenID Connect provides connections to third-party authentication services to authenticate users in {{% ctx %}} Gateway, using Multi-Factor Authentication (MFA) if the provider supports it.
+
+The OpenID Connect tab currently only supports the Microsoft Entra provider but allows for one or more instances to be configured.
+
+{{% ctx %}} Roles and Flow Editor permissions can be assigned to groups set up in Microsoft Entra.
+
+The fields available are:
+
+* `Provider Type` – the OIDC provider type. Currently, only Microsoft is the OIDC provider supported.
+* `Identifier` – free-format, friendly unique name for this provider.
+* `Display Name` – the text displayed in the {{% ctx %}} Gateway sign-in button.
+* `Authority` – the URL to send authentication requests to.
+* `Tenant Identifier` – the Microsoft Entra Tenant ID for the organisation managing authentication.
+* `Client Identifier` – the unique identifier to identify the {{% ctx %}} Gateway application to the authentication provider.
+* `Client Secret` – the client secret that validates the {{% ctx %}} Gateway application with the authentication provider.
+
+## Actions
+
+### Configure LDAP Authentication
+
+LDAP Authentication can be configured by selecting the `LDAP` tab and entering the connection information. Once the details have been entered it is necessary to test the connection before being able to save them.
+
+See the [Configure LDAP Authentication][Configure LDAP Authentication tutorial] tutorial for a step-by-step guide.
+
+### Add New OpenID Connect Authentication Provider
+
+To configure {{% ctx %}} Gateway to use OpenID Connect Authentication, the application must be registered and configured with the provider. For assistance with configuring this see [FAQs][configure OIDC provider].
+
+An Open ID Connect provider can be added to the authentication providers by selecting the `OpenID Connect` tab, then selecting the `+ New Provider` option and entering the connection information. Once the details have been entered it is necessary to validate the connection before being able to save them.
+
+See the [Add New OpenID Connect Authentication Provider][Add New OpenID Connect Authentication Provider tutorial] tutorial for a step-by-step guide.
+
+## Remarks
+
+### Known Limitations
+
+* Currently, only Microsoft Entra OIDC is supported.
+* OpenID Connect only validates the format of the data entered in the OIDC form; it does not validate that a connection to the provider can be established.
+* OpenID Connect does not currently offer any filtering of the groups imported into {{% ctx %}} Gateway.
+
+## See Also
+
+### Related Concepts
+
+None
+
+### Related Tutorials
+
+* [Configure LDAP Authentication][Configure LDAP Authentication tutorial]
+* [Add New OpenID Connect Authentication Provider][Add New OpenID Connect Authentication Provider tutorial]
+
+[OIDC]: {{< ref "#openid-connect" >}}
+[LDAP]: {{< ref "#ldap" >}}
+
+[Add New OpenID Connect Authentication Provider tutorial]: {{< url path="Cortex.Tutorials.Administration.Authentication.OpenID" >}}
+[Configure LDAP Authentication tutorial]: {{< url path="Cortex.Tutorials.Administration.Authentication.LDAP" >}}
+
+[configure OIDC provider]: {{< url path="Cortex.Faqs.ConfigureOidcAuthentication.MainDoc" >}}
+[DNs]: {{< url path="MSDocs.Windows.Ldap.DNs" >}}

content/en/docs/2025.11/Guides/user-guides/user-interfaces/gateway/Admin/Authorisation.md

@@ -0,0 +1,63 @@
+---
+title: "Authorisation"
+linkTitle: "Authorisation"
+description: "Configure roles used to control access to functionality in {{% ctx %}} Gateway."
+weight: 30
+---
+
+# {{% param title %}}
+
+## Summary
+
+The Authorisation page is used to assign roles within {{% ctx %}} Gateway based on the membership of Active Directory Security Groups ([LDAP Authentication][]) and Microsoft Entra Groups ([OIDC Authentication][]).
+
+## Anatomy
+
+{{< figure src="/images/Authorisation.png" title="Authorisation" >}}
+
+The Authorisation grid allows roles to be assigned to groups:
+
+* `Name` shows:
+  * For [LDAP Authentication][], the Active Directory domain, organisational units, containers and Security Groups in a hierarchical tree; these groups are limited to those defined by the Base DNs configured.
+  * For [OIDC Authentication][], the Provider's display name and groups in a hierarchical tree.
+
+* `Type` identifies the type of object for that row.
+* `Admin` and `Studio` are roles that can be assigned and contain checkboxes to indicate which object has access to which role.
+
+  * Admin – provides access to administrative functions within {{% ctx %}} Gateway, including the ability to set user roles and permissions, import and export flows, creation and management of packages, etc.
+  * Studio – provides access to set the permissions to view and/or edit any flow in the Flow Editor.
+
+  Both the `Admin` and `Studio` roles may be assigned to a single group or groups of groups, to provide access to both the administrative functions in {{% ctx %}} Gateway and flows in the Flow Editor.
+
+  Note: The `LiveView` and `Reporting` roles do not apply to {{% ctx %}}.
+
+## Actions
+
+### Assign {{% ctx %}} Roles to Security Groups
+
+If an individual Group object is checked ({{< image src="/images/Authorisation - Individual Object Checked.png" >}}), then its parent objects will also be implicitly set ({{< image src="/images/Authorisation - Parent Object Implicit.png" >}}). If a parent object is checked ({{< image src="/images/Authorisation - Parent Object Explicit.png" >}}), all its child objects will be implicitly set ({{< image src="/images/Authorisation - Child Object Implicit.png" >}}). Objects may be individually unset by clicking the checked checkbox.
+
+When all the role assignments have been completed, click the Save Changes button to commit the current role assignments.
+
+See the [Assign {{% ctx %}} Roles to Security Groups][Assign {{% ctx %}} Roles to Security Groups tutorial] tutorial for a step-by-step guide.
+
+## Remarks
+
+### Known Limitations
+
+* The key shown at the bottom of the page to convey the role assignment state is incorrect.
+
+## See Also
+
+### Related Concepts
+
+None
+
+### Related Tutorials
+
+* [Assign {{% ctx %}} Roles to Security Groups][Assign {{% ctx %}} Roles to Security Groups tutorial]
+
+[Assign {{% ctx %}} Roles to Security Groups tutorial]: {{< url path="Cortex.Tutorials.Administration.Authorisation.AssignRoles" >}}
+
+[LDAP Authentication]: {{< url path="Cortex.Guides.UserGuides.UserInterfaces.Gateway.Admin.Authentication.LdapAuth" >}}
+[OIDC Authentication]: {{< url path="Cortex.Guides.UserGuides.UserInterfaces.Gateway.Admin.Authentication.OidcAuth" >}}

content/en/docs/2025.11/Tutorials/Administration/authentication.md

@@ -0,0 +1,16 @@
+---
+title: "Authentication"
+linkTitle: "Authentication"
+description: "This section includes tutorials about setting up authentication providers used to control access to {{% ctx %}} Gateway."
+weight: 20
+---
+
+# {{% param title %}}
+
+## Configure LDAP Authentication
+
+{{< scribe title="Configure_LDAP_Authentication_Settings" id="vbQRAuUUTtm0oi1uV6Py9w" >}}
+
+## Add New OpenID Connect Authentication Provider
+
+{{< scribe title="Add_New_OpenID_Connect_Authentication_Provider_for_CORTEX_Gateway" id="2bk2wz1MQPOX-bR3-xhw5A" >}}

content/en/docs/2025.11/Tutorials/Administration/authorisation.md

@@ -0,0 +1,12 @@
+---
+title: "Authorisation"
+linkTitle: "Authorisation"
+description: "This section includes tutorials about configuring authorisation."
+weight: 20
+---
+
+# {{% param title %}}
+
+## Assign {{% ctx %}} Roles to Security Groups
+
+{{< scribe title="How_to_Assign_CORTEX_Gateway_Roles_to_Active_Directory_Security_Groups" id="Vs8h3Ie8Tqa9kflCoAj_yg" >}}

content/en/docs/2025.9/FAQs/configure-oidc-authentication/_index.md

@@ -0,0 +1,6 @@
+---
+title: "How do I configure OpenID Connect authentication?"
+linkTitle: "How do I configure OpenID Connect authentication?"
+description: "Instructions on how to configure OpenID Connect authentication for {{% ctx %}} Gateway."
+weight: 300
+---