diff --git a/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_config_to_connect_to_cloud.md b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_config_to_connect_to_cloud.md new file mode 100644 index 0000000000..521349f9f8 --- /dev/null +++ b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_config_to_connect_to_cloud.md @@ -0,0 +1,58 @@ +--- +uid: SAML_config_to_connect_to_cloud +--- + +# Additional configuration for systems connected to dataminer.services + +When you connect a DataMiner System for which SAML has already been configured to dataminer.services, three URLs need to be added to the identity provider configuration and the DataMiner metadata file: + +1. Update the identity provider configuration: + + - If you are using **Microsoft Entra ID** or **Azure B2C**, update the configuration of your DataMiner enterprise application: + + 1. Navigate to ``portal.azure.com`` and log in. + + 1. In the search box at the top, enter *Enterprise applications* to go to the Enterprise Applications page. + + 1. Select the application that was created for DataMiner. + + 1. In the pane on the left on your DataMiner application page, click *Single sign-on*. + + 1. Next to *Basic SAML Configuration*, click *Edit*. + + 1. Under *Reply URL*, add the following URLs, replacing `` with the DNS name in the *spMetadata.xml* file and `` with the name of the organization: + + - `https://-.on.dataminer.services/API/` + - `https://-.on.dataminer.services/account-linking` + - `https://-.on.dataminer.services/account-linking/` + + > [!NOTE] + > Note the trailing "/". + + Example of remote access URL: `https://dataminer-skyline.on.dataminer.services` + + In this example, the DMS DNS name is "dataminer" and the organization name is "skyline". + + 1. In the top-left corner, click *Save*. + + - If you are using **Okta**, add the three URLs mentioned above to *Other Requestable SSO URLs*. See [Configuring SAML with Okta](xref:SAML_using_Okta). + +1. Update your DataMiner metadata file: + + 1. Open the file *spMetadata.xml*. Usually, this is located in the `C:\Skyline DataMiner` folder. + + 1. Add the new URLs to this file as illustrated below. + + In the example below, the remote access URL is `https://dataminer-skyline.on.dataminer.services`: + + ```xml + + + + ... + + + + + + ``` diff --git a/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Azure_B2C.md b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Azure_B2C.md new file mode 100644 index 0000000000..34523ba8e9 --- /dev/null +++ b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Azure_B2C.md @@ -0,0 +1,36 @@ +--- +uid: SAML_using_Azure_B2C +--- + +# Configuring SAML with Azure B2C as identity provider + +From DataMiner 10.2.6/10.3.0 onwards, DataMiner supports Azure B2C as an identity provider for external authentication via SAML. + +To configure this: + +1. Configure Azure B2C. See [Azure Active Directory B2C documentation | Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory-b2c/). + +1. Set up an Entra ID Enterprise application. You can do this in the same way as for [Entra ID](xref:SAML_using_Entra_ID#setting-up-a-microsoft-entra-id-enterprise-application). + +1. Create a DataMiner metadata file. You can do this in the same way as for [Entra ID](xref:SAML_using_Entra_ID#creating-a-dataminer-metadata-file). + +1. Configure policies for Azure B2C. See [Tutorial: Create user flows and custom policies in Azure Active Directory B2C | Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy). + +1. Get the metadata URL: + + 1. In Azure, go to *App registrations*, select your app, and select *Overview* > *Endpoints*. + + ![App endpoints](~/user-guide/images/SAML_B2C_endpoints.png) + + 1. Select the Azure AD B2C SAML metadata endpoint, e.g. `https://dataminerservices.b2clogin.com/dataminerservices.onmicrosoft.com//Samlp/metadata`, and replace \ with the name of the policy you created earlier. + +1. Configure DataMiner to use external authentication. You can do this in the same way as for [Entra ID](xref:SAML_using_Entra_ID#configuring-dataminerxml-to-use-external-authentication). + + For the *ipMetadata* link, use the link created in the previous step. + +1. Configure DataMiner to automatically create users from Azure B2C. You can do this in the same way as for [Entra ID](xref:SAML_using_Entra_ID#configuring-automatic-creation-of-users-authenticated-by-entra-id-using-saml). + + > [!NOTE] + > + > - If you use Azure B2C, users can only be provisioned automatically. Provisioning users by importing them is not possible. + > - To create SAML users in DataMiner using Azure B2C, a domain is required in the usernames. For this reason, email addresses must be used as the usernames. If the default username of the identity provider is not a valid email address, add a `` element to the `` element in *DataMiner.xml* that refers to a claim containing a valid email address. diff --git a/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Entra_ID.md b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Entra_ID.md new file mode 100644 index 0000000000..e739d5d431 --- /dev/null +++ b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Entra_ID.md @@ -0,0 +1,474 @@ +--- +uid: SAML_using_Entra_ID +--- + +# Configuring SAML with Microsoft Entra ID as identity provider + +From DataMiner 10.1.5 onwards, Microsoft Entra ID (known as Azure Active Directory prior to July 2023) is supported as an identity provider for external authentication via SAML. + +To configure external authentication with Entra ID as the identity provider, you will first need to [set up authentication](#configuring-authentication). Once this is done, you will need to [configure how users should be provisioned](#configuring-user-provisioning). + +## Configuring authentication + +To configure authentication, follow these steps: + +1. [Set up a Microsoft Entra ID Enterprise application](#setting-up-a-microsoft-entra-id-enterprise-application) + +1. [Create a DataMiner metadata file](#creating-a-dataminer-metadata-file) + +1. [Configure DataMiner.xml to use external authentication](#configuring-dataminerxml-to-use-external-authentication) + +### Setting up a Microsoft Entra ID Enterprise application + +To set up external authentication, you first need to create an enterprise application in Entra ID. + +> [!NOTE] +> +> - In DataMiner versions **prior to DataMiner 10.2.0/10.2.1**, using an enterprise application is **not yet supported**, so you should instead register DataMiner on the *App registrations* page. However, note that many features will not be available with such a setup, so we highly recommend upgrading to a more recent DataMiner version and setting up an enterprise application instead. +> - Only a Global Administrator, Application Administrator, Cloud Application Administrator, and Application Developer have the necessary permissions to create enterprise applications. + +1. In Entra ID, register DataMiner as an enterprise application: + + 1. Navigate to ``portal.azure.com`` and log in. + + 1. In the search box at the top, enter *Enterprise applications* to go to the Enterprise Applications page. + + 1. At the top, click *New application*. + + ![Adding an enterprise app](~/user-guide/images/SAML_Add_enterprise_app.png) + + 1. Click *Create your own application*. + + 1. Select *Integrate another application you don’t find in the gallery* and click *Create*. + +1. In the pane on the left, go to *Users and groups*. + +1. Use the *Add user/group* button to add the necessary users and groups and assign the necessary roles. + + ![Adding users/groups](~/user-guide/images/SAML_Add_users_groups.png) + + > [!NOTE] + > Make sure the *Email* field is filled in for all users. Azure will not authenticate users with an empty *Email* field. + +1. Go to *Single sign-on*, and click *Edit* next to *Basic SAML Configuration*. + + ![Editing the basic SAML configuration](~/user-guide/images/SAML_edit_basic_config.png) + +1. Configure the following settings for the basic SAML configuration: + + 1. Set *Entity ID* to the IP address or the DNS name of your DataMiner System, for example ``https://dataminer.example.com/``. + + 1. Under *Reply URL*, specify the following URL(s), replacing ``dataminer.example.com`` with the IP address or DNS name of your DataMiner System (note the trailing "/"): + + - From DataMiner 10.3.5 onwards: + + - ``https://dataminer.example.com/API/`` + + - For older DataMiner versions only: + + - ``https://dataminer.example.com/root/`` + + - ``https://dataminer.example.com/ticketing/`` + + - ``https://dataminer.example.com/jobs/`` + + - ``https://dataminer.example.com/monitoring/`` + + - ``https://dataminer.example.com/dashboard/`` + + - ``https://dataminer.example.com/API/`` + + - ``https://dataminer.example.com/`` + + - If the DMA is connected to dataminer.services, also add the following URLs, replacing `` with the DNS name of the DataMiner System and `` with the name of the organization + + - `https://-.on.dataminer.services/API/` + + - `https://-.on.dataminer.services/account-linking` + + - `https://-.on.dataminer.services/account-linking/` + + ![Editing the basic SAML configuration](~/user-guide/images/SAML_Reply_URLs.png) + + 1. Set *Sign on URL* to the IP address or DNS name of your DataMiner System, for example ``https://dataminer.example.com/``. + + 1. In the top-left corner, click *Save*. + +1. Still on the *Single sign-on* page, look for the *SAML Certificates* section and copy the *App Federation Metadata Url*. + + You will need this later when [configuring DataMiner.xml](#configuring-dataminerxml-to-use-external-authentication). + +### Creating a DataMiner metadata file + +1. Create a new XML file named *spMetadata.xml*. + + We recommend placing this file in the `C:\Skyline DataMiner` folder, though it is possible to put it in a different location. + +1. Copy the following template into *spMetadata.xml*: + + - From DataMiner 10.3.5 onwards: + + ```xml + + + + + + + ``` + + - Older DataMiner versions: + + ```xml + + + + + + + + + + + + + ``` + + - For a DMA connected to dataminer.services, add the three following additional bindings within the `` element: + + ```xml + + ... + + + + + ``` + +1. Replace [ENTITYID] with the IP address or the DNS name of your DataMiner System. This must be the same as the *Entity ID* you specified while setting up the Microsoft Entra ID Enterprise application. + +1. Replace ``https://dataminer.example.com`` with the IP address or the DNS name of your DataMiner System. The specified URL(s) must match the *Reply URL* you specified while setting up the Microsoft Entra ID Enterprise application. + +1. If you are configuring this for a DataMiner Agent connected to dataminer.services, replace `` with the DNS name of the DataMiner System and `` with the name of the organization. + + For example, if the DNS name is "dataminer" and the organization name is "skyline", the first URL is `https://dataminer-skyline.on.dataminer.services/API/`. + +1. If you are using DataMiner 10.2.1/10.2.0 or higher, make sure ``WantAssertionsSigned`` is set to *true*. + + > [!NOTE] + > This flag must be set to *true* because SAML responses without signatures can be freely edited to tamper with permissions for the application, leading to severe vulnerabilities. In DataMiner versions prior to DataMiner 10.2.1/10.2.0, setting this flag to true is not yet supported, so we highly recommend upgrading to a more recent DataMiner version. + +### Configuring DataMiner.xml to use external authentication + +1. Go to the folder `C:\Skyline DataMiner` and open the *DataMiner.xml* file. + +1. In *DataMiner.xml*, configure the `` tag as illustrated in the example below: + + ```xml + + ... + + ... + + ``` + + - **type**: `SAML` (Identity federation using SAML assertions) + + - **ipMetadata**: The path to or the URL of the identity provider's metadata file, which you copied while [setting up the Microsoft Entra ID Enterprise application](#setting-up-a-microsoft-entra-id-enterprise-application). + + - **spMetadata**: The path to or the URL of the [DataMiner metadata file](#creating-a-dataminer-metadata-file) you created earlier. + + - **timeout**: Optional. The amount of time DataMiner should wait for the user to be authenticated by the identity provider. If this attribute is not specified, DataMiner will wait 300 seconds (5 minutes). + +1. Save and close the file, and restart the DMA. + +## Configuring user provisioning + +Once authentication has been configured, you need to make sure users are provisioned. There are two ways to do this: + +- By [importing users and groups from Microsoft Entra ID into DataMiner](#configuring-dataminer-to-import-users-and-groups-from-microsoft-entra-id). +- By [configuring automatic creation of users](#configuring-automatic-creation-of-users-authenticated-by-entra-id-using-saml). This way, when a user authenticates using SAML, they will automatically be added in DataMiner. + +> [!CAUTION] +> If there are two DataMiner users who share the same email address, both users will not be able to log in. To prevent this from happening, we recommended using only one method to add users. For example, do not add Windows domain users if the Entra ID users use the same email address. + +### Configuring DataMiner to import users and groups from Microsoft Entra ID + +> [!NOTE] +> If you import over 1000 users or groups, it may take some time before the import is complete. Avoid importing over 10,000 users and groups, as this can result in a timeout. + +#### [From DataMiner 10.1.11/10.2.0 onwards](#tab/tabid-1) + +1. Navigate to ``portal.azure.com`` and log in. + +1. In the search box at the top, enter *App registrations* to go to the App registrations page. + +1. Select *All applications* and use the filter box to find the application you created for DataMiner. + +1. Select the application to view a page with more detailed information. + +1. Gather the following information from this page: + + - *Application (client) ID* + + - *Object ID* (optional from 10.3.11/10.4.0 onwards) + + - *Tenant ID* + + These GUIDs identify the application (DataMiner) in the Entra ID platform, and identify the users & groups directory on the Azure portal, respectively. You will need these later in this procedure. + + ![SAML application info](~/user-guide/images/SAML_application_info.png) + + > [!NOTE] + > Do not use the *Object ID* under *Azure Active Directory > Enterprise applications > [your application name]*. This is a different Object ID, which will not work for this procedure. + +1. In the pane on the left, select *Certificates & secrets*. + + 1. In the *Client secrets* section, select *New client secret*. + + ![New client secret](~/user-guide/images/SAML_New_client_secret.png) + + 1. Enter a description and an expiration date for the application secret, and click *Add*. + + ![Add client secret](~/user-guide/images/SAML_Add_client_secret.png) + + 1. Copy the secret value for later on. You will need this value later in this procedure. + + > [!IMPORTANT] + > Once you leave this page, you will no longer be able to access the secret value. + +1. Stop the DataMiner Agent for which you want to configure this. + + > [!NOTE] + > It is possible to configure different methods of authentication for different DMAs in a DataMiner System. You can for example configure one DMA to import users and groups from Entra ID, but use local accounts to log in on a different DMA. + +1. On the DataMiner server, go to the folder `C:\Skyline DataMiner` and open the *DataMiner.xml* file. + +1. In *DataMiner.xml*, specify the information you previously gathered using the same syntax as in the following example: + + ```xml + + ``` + +1. Save the file and restart DataMiner. + + > [!NOTE] + > After you restart DataMiner, the specified client secret will be replaced by a GUID in the *DataMiner.xml* file. + +1. In the Azure portal, go back to the root page for the DataMiner application under *App registrations*. + +1. In the pane on the left, select *API Permissions*. + +1. Make sure the following permissions are enabled: + + - Microsoft Graph > GroupMember.Read.All – Application – Read groups memberships + + - Microsoft Graph > User.Read.All – Application - Read all users' full profiles + + - Microsoft Graph > User.Read – Delegated – Sign in and read user profile + + - Microsoft Graph > Application.Read.All – Application – Read applications + + > [!NOTE] + > From DataMiner 10.3.12 onwards, the *Application.Read.All* permission is optional. However, if you do not enable this permission, you will not get a warning if your client secret is about to expire, so we **strongly recommend that you enable this**. If this is enabled, you will get the following notice in the Alarm Console when appropriate: *Your Azure AD application's client secret is expiring soon.* + +1. Open DataMiner Cube and log in with an existing Administrator account. + +1. Add the users/groups as described under [Adding a user](xref:Adding_a_user) and [Adding a user group](xref:Adding_a_user_group). Select to add an existing user or group in order to add users and groups available on Entra ID. + +1. When you have added the necessary users, configure their permissions. See [Configuring a user group](xref:Configuring_a_user_group). + + Users will now be able to log in to DataMiner with any of the Entra ID user accounts you have added, using either the domain and username (DOMAIN\\user) or the email address. + +#### [Older DataMiner versions](#tab/tabid-2) + +While it is possible to use DataMiner versions prior to DataMiner 10.1.11/10.2.0 (starting from DataMiner 10.1.5), we do not recommend this. If you do wish to continue using an older DataMiner version, follow the procedure below. + +1. Navigate to ``portal.azure.com`` and log in. + +1. In the search box at the top, enter *App applications* to go to the App registrations page. + +1. Select *All applications* and use the filter box to find the application you created for DataMiner. + +1. Select the application to view a page with more detailed information. + +1. Gather the following information from this page: + + - *Application (client) ID* + + - *Object ID* (optional from 10.3.11/10.4.0 onwards) + + - *Tenant ID* + + These GUIDs identify the application (DataMiner) in the Entra ID platform, and identify the users & groups directory on the Azure portal, respectively. You will need these later in this procedure. + + > [!NOTE] + > Do not use the *Object ID* under *Azure Active Directory > Enterprise applications > [your application name]*. This is a different Object ID, which will not work for this procedure. + +1. Copy the *Username* and *Password* of the Entra ID user account that DataMiner will use to request data from Azure. Technically this can be any account, but we recommend that you create an account that will be use exclusively for this purpose. + +1. Stop the DataMiner Agent for which you want to configure this. + + > [!NOTE] + > It is possible to configure different methods of authentication for different DMAs in a DataMiner System. You can for example configure one DMA to import users and groups from Entra ID, but use local accounts to log in on a different DMA. + +1. On the DataMiner server, go to the folder `C:\Skyline DataMiner` and open the *DataMiner.xml* file. + +1. In *DataMiner.xml*, specify the information you previously gathered using the same syntax as in the following example: + + ```xml + + ``` + +1. Save the file and restart DataMiner. + + > [!NOTE] + > After you restart DataMiner, the specified password will be replaced by a GUID in the *DataMiner.xml* file. + +1. In the Azure portal, go back to the root page for the Data Miner application under *App registrations*. + +1. In the pane on the left, select *API Permissions*. + +1. Make sure the following permissions are enabled: + + - Microsoft Graph > Application.Read.All – Delegated – Read applications + + - Microsoft Graph > GroupMember.Read.All – Delegated – Read groups memberships + + - Microsoft Graph > User.Read – Delegated – Sign in and read user profile + + - Microsoft Graph > User.Read.All – Delegated – Read all users' full profiles + +1. Open DataMiner Cube and log in with an existing Administrator account. + +1. Add the users/groups as described under [Adding a user](xref:Adding_a_user) and [Adding a user group](xref:Adding_a_user_group). Select to add an existing user or group in order to add users and groups available on Entra ID. + +1. When you have added the necessary users, configure their permissions. See [Configuring a user group](xref:Configuring_a_user_group). + + Users will now be able to log in to DataMiner with any of the Entra ID user accounts you have added, using either the domain and username (DOMAIN\\user) or the email address. + +*** + +### Configuring automatic creation of users authenticated by Entra ID using SAML + +From DataMiner 10.2.0/10.1.12 onwards, users authenticated by Entra ID using SAML can be automatically created and assigned to groups in DataMiner. This is often referred to as JIT (Just-In-Time) Provisioning. + +There are two ways to configure this setup: with or without group claims. + +- With group claims, when a user logs in for the first time, they will be added to an existing group that exists both in Entra ID and in DataMiner. + +- Without group claims, any user that logs in for the first time will be added to one default security group, which you will need to configure during the setup detailed below. This is easier to configure, but has the disadvantage that user information that is created will not be updated. + +#### [With group claims](#tab/tabid-3) + +1. Navigate to ``portal.azure.com`` and log in. + +1. In the search box at the top, enter *Enterprise applications* to go to the Enterprise Applications page. + +1. Select the application you created for DataMiner. + +1. In the pane on the left on your DataMiner application page, click *Single sign-on*. + +1. Next to *Attributes & Claims*, click *Edit*. + + ![Edit attributes & claims](~/user-guide/images/SAML_Edit_claim.png) + +1. Click *Add a group claim*. + + ![Add a group claim](~/user-guide/images/SAML_Add_group_claim.png) + +1. Configure the group claim: + + 1. Select to include *Groups assigned to the application*. + + With this option, the groups you configured when [setting up the application](#setting-up-a-microsoft-entra-id-enterprise-application) will be included in the group claim. + + 1. Under *Source attribute*, we recommend selecting *sAMAccountName*. + + 1. Optionally, expand the advanced options to add a filter or customize the name of the group claim. + + 1. Click *Save*. + + ![Group claim configuration](~/user-guide/images/SAML_Group_claim_config.png) + + > [!NOTE] + > The account name of the group will only be sent via SAML when the groups are synchronized (from an on-premises AD). Otherwise, the ID of the group will be sent instead. + +1. In DataMiner Cube, add the groups corresponding with the groups you included in the group claim in Entra ID. See [Adding a user group](xref:Adding_a_user_group). + +1. Stop DataMiner. + +1. Go to the `C:\Skyline DataMiner` folder and open the *DataMiner.xml* file. + +1. In *DataMiner.xml*, add the `` tag as illustrated in the example below: + + ```xml + + ... + + + http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress + http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname + http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname + [group claim name] + + + ... + + ``` + +1. Save the *DataMiner.xml* file. + +1. Restart the DataMiner Agent. + +#### [Without group claims](#tab/tabid-4) + +1. Make sure a group has been added in DataMiner that can be used to automatically add users to. See [Adding a user group](xref:Adding_a_user_group). + +1. Stop DataMiner. + +1. Go to the `C:\Skyline DataMiner` folder and open the *DataMiner.xml* file. + +1. In *DataMiner.xml*, add the `` tag as illustrated in the example below: + + ```xml + + ... + + + http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress + http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname + http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname + [existing DataMiner group] + + + ... + + ``` + +1. Save the *DataMiner.xml* file. + +1. Restart the DataMiner Agent. + +*** diff --git a/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Okta.md b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Okta.md new file mode 100644 index 0000000000..efa0843790 --- /dev/null +++ b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/SAML_using_Okta.md @@ -0,0 +1,205 @@ +--- +uid: SAML_using_Okta +--- + +# Configuring SAML with Okta as the identity provider + +> [!IMPORTANT] +> We strongly recommend that you upgrade to DataMiner 10.3.0 or 10.3.2 to use this feature. While Okta is supported from DataMiner 10.1.11 onwards, a software issue may make it impossible for users to log in with Okta prior to DataMiner 10.3.0/10.3.2. + +One of the identity providers that is supported for external authentication via SAML is Okta. + +There are two ways to configure this setup: with or without group claims. If group claims are used, when a user logs in for the first time, they will be added to an existing group that exists both in Okta and in DataMiner. If no group claims are used, any user that logs in for the first time will be added to one default security group, which you will need to configure during the procedure detailed below. Both possibilities are detailed below. + +> [!NOTE] +> When Okta is used, automatic user creation must be enabled. It is currently not possible to import users and groups from Okta. As an alternative, you can add [local users](xref:User_management#local-users) or [domain users](xref:User_management#user-directories) in DataMiner, and then you can have Okta authenticate these users by following the guide below, except that you omit the *AutomaticUserCreation* tag in *DataMiner.xml*. + +1. Launch Okta's App Integration Wizard. + + 1. In the Admin Console, go to *Applications \> Applications*. + + 1. Click *Create App Integration*. + + 1. To create a SAML integration, select "SAML 2.0" as the *Sign-on method*. + + 1. Click *Next*. + +1. Configure the general settings: + + - **App name**: The name of your application. Fill in “DataMiner” (or some other preferred name). + + - **App logo**: Optional logo to be linked to your application. + + - Format: PNG, JPG or GIF + + - Max. size: 1 MB + + - Min. resolution: 420 x 120 pixels + + > [!TIP] + > We recommend using a PNG image with a transparent background and a landscape orientation. + +1. Configure the Okta SAML settings: + + - **Single sign on URL**: The location where the SAML assertion is sent with a POST operation. + + - In this box, enter IP address or the DNS name of your DataMiner System, followed by `/root/`, e.g. ``https://dataminer.example.com/root/``. + + - Select the following checkboxes: + + - *Use this for Recipient URL and Destination URL* + + - *Allow this app to request other SSO URLs* + + - Open *Show Advanced Settings* and enter the following additional URLs to *Other Requestable SSO URLs* (replacing `dataminer.example.com` with the actual IP address or DNS name of your DMS): + + From DataMiner 10.3.5 onwards: + + - ``https://dataminer.example.com/API/`` + + Older DataMiner versions: + + - ``https://dataminer.example.com/root/`` + + - ``https://dataminer.example.com/API/`` + + - ``https://dataminer.example.com/dashboard/`` + + - ``https://dataminer.example.com/monitoring/`` + + - ``https://dataminer.example.com/jobs/`` + + - ``https://dataminer.example.com/ticketing/`` + + If the DMA is connected to dataminer.services, also add the following URLs, replacing `` with the DNS name of the DataMiner System and `` with the name of the organization + + - `https://-.on.dataminer.services/API/` + + - `https://-.on.dataminer.services/account-linking` + + - `https://-.on.dataminer.services/account-linking/` + + > [!NOTE] + > The indexes here should be the same as the indexes in `C:\Skyline DataMiner\okta-sp-metadata.xml`, which you will create later in this procedure. + + > [!TIP] + > See also: [Additional configuration for systems connected to dataminer.services](xref:SAML_config_to_connect_to_cloud) + + - **Audience URI (SP Entity ID)**: The intended audience of the SAML assertion. + + In this box, enter the IP address or the DNS name of your DataMiner System, e.g. ``https://dataminer.example.com/``. + + - **Name ID format**: The username format you are sending in the SAML Response. + + Select "EmailAddress". + + - **Application username**: The default value to use for the username with the application. + + Select "Email". + + - **Attribute Statements**: Add the following attribute statements, all with "Basic" format: + + - name "Email", value "user.email" + + - name "Firstname", value "user.firstName" + + - name "Lastname", value "user.lastName" + + - **When using group claims:** + + - Create groups in DataMiner with the exact same names as in Okta (this is case-sensitive). See [Adding a user group](xref:Adding_a_user_group). + + - Add a group attribute statement. + + - Use the name "userGroups", and "Basic" format. + + - Under *Filter*, select the type of filter you want, and then add a statement that will match the groups you want to send for that user. + + > [!Note] + > + > - The name fields can be anything you want, but we recommend giving them a name that clearly reflects the claim they refer to. All of these are case-sensitive. + > - Make sure that what you put under "name" for each claim matches exactly with the claim names in *DataMiner.xml*. + +1. Stop DataMiner. + +1. Go to the *C:\\Skyline DataMiner* folder and open the *DataMiner.xml* file. + +1. In *DataMiner.xml*, configure the *\* tag as illustrated in the example below: + + ```xml + + ... + + + [email claim name] + [firstname claim name] + [lastname claim name] + [group claim name] + + + ... + + ``` + + > [!NOTE] + > + > - The claim name refers to the attribute statement names that were added in Okta. + > - User groups have to exist in DataMiner both for *Groups* claims set to true and to false. Make sure all the necessary groups have been added earlier, so that it will be possible to add users to them. + > - If you set the *claims* attribute of the *Groups* element to "false", no claims will be used to add users to groups. In this case: + > - Instead of a claim for user groups, replace `[group claim name]` with a security group that exists in DataMiner as described above. + > - It will only be possible to add a user to a single group. + > - The user information that is created will not be updated. + +1. Save the *DataMiner.xml* file. + +1. Open the *Sign On* tab of your Okta application and scroll down to *SAML Signing Certificates*. + +1. In the *Actions* column of the *Active* certificate, click *View IdP metadata*. + +1. Save this identity provider’s metadata XML file to the DataMiner Agent, e.g. `C:\Skyline DataMiner\okta-ip-metadata.xml`. + +1. Copy the following template to a new XML file named e.g. `C:\Skyline DataMiner\okta-sp-metadata.xml` to create the service provider’s metadata file. You can find the EntityID in the previously created file `C:\Skyline DataMiner\okta-ip-metadata.xml`. + + From DataMiner 10.3.5 onwards: + + ```xml + + + + + + + ``` + + Older DataMiner versions: + + ```xml + + + + + + + + + + + + ``` + + For a DMA connected to dataminer.services, add the three following additional bindings within the `` element: + + ```xml + + ... + + + + + ``` + +1. Restart DataMiner. diff --git a/user-guide/Troubleshooting/Procedures/Troubleshooting_SAML_Issues.md b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/Troubleshooting_SAML_Issues.md similarity index 92% rename from user-guide/Troubleshooting/Procedures/Troubleshooting_SAML_Issues.md rename to user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/Troubleshooting_SAML_Issues.md index 034d207f36..4864f545d8 100644 --- a/user-guide/Troubleshooting/Procedures/Troubleshooting_SAML_Issues.md +++ b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_SAML/Troubleshooting_SAML_Issues.md @@ -21,7 +21,7 @@ When you encounter SAML issues, investigate the logs detailed below, in the spec ## Troubleshooting > [!IMPORTANT] -> Before proceeding with any troubleshooting procedures, we highly recommend reading [Configuring external authentication via an identity provider using SAML](xref:Configuring_external_authentication_via_an_identity_provider_using_SAML). +> Before you proceed with any troubleshooting procedures, we highly recommend that you read [Configuring SAML settings](xref:Configuring_external_authentication_via_an_identity_provider_using_SAML). This troubleshooting section addresses the following common SAML issues: @@ -37,7 +37,7 @@ This troubleshooting section addresses the following common SAML issues: ### Partial setup -Partial setups are not compatible with SAML. Ensure that all settings are correctly configured for both DataMiner and the identity provider before attempting to log in. See [Configuring external authentication via an identity provider using SAML](xref:Configuring_external_authentication_via_an_identity_provider_using_SAML). +Partial setups are not compatible with SAML. Ensure that all settings are correctly configured for both DataMiner and the identity provider before attempting to log in. See [Configuring SAML settings](xref:Configuring_external_authentication_via_an_identity_provider_using_SAML). ### SAML authentication issues in Cube/online @@ -127,7 +127,7 @@ Here are some other common SAML-related issues: - Ensure that the username is always an email address. - - In [Azure setups](xref:Configuring_external_authentication_via_an_identity_provider_using_SAML#identity-providers), missing email field values can cause problems, even though the default username is an email. + - If [Microsoft Entra ID](xref:SAML_using_Entra_ID) is used as the identity provider for external authentication, missing email field values can cause problems, even though the default username is an email. ### Error messages diff --git a/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_external_authentication_via_an_identity_provider_using_SAML.md b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_external_authentication_via_an_identity_provider_using_SAML.md index a5638421a0..2e8a8533e1 100644 --- a/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_external_authentication_via_an_identity_provider_using_SAML.md +++ b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Configuring_external_authentication_via_an_identity_provider_using_SAML.md @@ -3,529 +3,42 @@ uid: Configuring_external_authentication_via_an_identity_provider_using_SAML keywords: Azure AD, AzureAD, Microsoft Entra ID, SAML, Okta, Azure B2C --- -# Configuring external authentication via an identity provider using SAML +# Configuring SAML settings -From DataMiner 9.6.11 onwards, it is possible to configure external authentication via an identity provider service using SAML (Security Assertion Markup Language). +If you want to configure your DataMiner System to use external authentication, the best way to do so is using SAML (Security Assertion Markup Language). This is supported from DataMiner 9.6.11 onwards. -## Requirements +To configure SAML, you will first need to set up authentication. For this, you need to generate a metadata file for the service provider (i.e. DataMiner) and a metadata file for the identity provider, and DataMiner and the identity provider need to exchange metadata files. This way, a trust relationship between the two is established. The following metadata must be shared between DataMiner and the identity provider service: Entity ID, Cryptographic Keys, Protocol Endpoints (bindings, locations). Once this is done, you then need to configure user provisioning. -- DataMiner integrates with **identity providers using version 2.0 of the SAML protocol**. Compatibility with older SAML versions is not supported. +You can find detailed information about this configuration for the different supported identity providers here: -- The identity provider must support **Redirect binding** for communication between the service provider and the identity provider. Most SAML identity providers support Redirect binding by default. +- [Microsoft Entra ID](xref:SAML_using_Entra_ID) (formerly Azure AD) +- [Azure B2C](xref:SAML_using_Azure_B2C) +- [Okta](xref:SAML_using_Okta) -- DataMiner uses service provider-initiated **Single Sign-On (SSO)** through Redirect binding. It does not support the use of POST or SOAP binding for requests. However, standard POST binding is used for responses. +Once everything has been correctly configured, if users try to log in to the DMA using external authentication via SAML, they will be redirected to a login page of the identity provider. That page will authenticate them and return a SAML response, which DataMiner will use to either grant or deny access. - > [!TIP] - > For a comprehensive understanding of the SAML process, including the encoding and encryption guidelines that DataMiner follows, refer to the official SAML Documentation: [SAML Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#5.1.2.SP-Initiated%20SSO:%20%20Redirect/POST%20Bindings|outline). - -## Establishing a trust relationship between the service provider and identity provider - -To configure external authentication via an identity provider service using SAML, a trust relationship must be established between the service provider (i.e. DataMiner) and the identity provider. This is done by exchanging SAML metadata files. - -The following metadata must be shared between the service provider (i.e. DataMiner) and the Identity Provider service: Entity ID, Cryptographic Keys, Protocol Endpoints (bindings, locations). +Please note the following: -> [!TIP] -> See also: [Troubleshooting SAML issues](xref:Troubleshooting_SAML_Issues) +- Any DataMiner Agent configured for SAML external authentication must be **accessible via [HTTPS](xref:Setting_up_HTTPS_on_a_DMA)**. -To configure this, follow the steps below: +- DataMiner integrates with **identity providers using version 2.0 of the SAML protocol**. Compatibility with older SAML versions is not supported. In addition, the identity provider must support **redirect binding** for communication between the service provider (i.e. DataMiner) and the identity provider. Most SAML identity providers support redirect binding by default. -1. Go to the *C:\\Skyline DataMiner* folder and open the *DataMiner.xml* file. +- DataMiner uses service provider-initiated **Single Sign-On (SSO)** through redirect binding. It does not support the use of POST or SOAP binding for requests. However, standard POST binding is used for responses. -1. In *DataMiner.xml*, configure the *\* tag as illustrated in the example below: + > [!TIP] + > For a comprehensive understanding of the SAML process, including the encoding and encryption guidelines that DataMiner follows, refer to the official SAML Documentation: [SAML Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0-cd-02.html#5.1.2.SP-Initiated%20SSO:%20%20Redirect/POST%20Bindings|outline). - ```xml - - ... - - ... - - ``` +- DataMiner will expect one of the claims provided by the identity provider to be the "name" claim: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`. This field must contain either the username or the email address. - | Attribute | Description | - | --------- | ----------- | - | type | SAML (Identity federation using SAML assertions) | - | ipMetadata | The path to or the URL of the identity provider's metadata file. The way in which to retrieve this metadata file will depend on the identity provider you are using. See [Identity providers](#identity-providers) | - | spMetadata | The path to or the URL of the service provider's metadata file. See [Creating a DataMiner metadata file](#creating-a-dataminer-metadata-file) | - | timeout | Optional attribute. The amount of time DataMiner should wait for the user to be authenticated by the identity provider. If this attribute is not specified, DataMiner will wait 300 seconds (5 minutes). | +- If a default username is not in email format or if DataMiner is unable to locate it, add a `` element to the `` element in *DataMiner.xml* that refers to a claim containing a valid email address tag. See [Configuring DataMiner.xml to use external authentication](xref:SAML_using_Entra_ID#configuring-dataminerxml-to-use-external-authentication). -1. Save and close the file, and restart the DMA. +- If there are two DataMiner users who share the same email address, both users will not be able to log in. To prevent this from happening, we recommended not using more than one method to add users. For example, do not add Windows domain users if the Entra ID users use the same email address. -Once this has been configured, if users try to log in to the DMA using external authentication via SAML, they will be redirected to a login page of the identity provider. That page will authenticate them and return a SAML response, which DataMiner can use to either grant or deny access. +- To use external authentication for DataMiner **Low-Code Apps**, you must use DataMiner **10.3.5 or higher**. -> [!NOTE] -> -> - From DataMiner 10.2.0/10.1.4 onwards, Cube uses the **Chromium** web browser engine to handle SAML external authentication. That engine supports a wider range of identity providers than the Internet Explorer engine that was used previously. -> - DataMiner **10.3.5** or higher is required to use external authentication for DataMiner **Low-Code Apps**. -> - DataMiner will expect one of the claims provided by the identity provider to be the **"name" claim**: ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name``. This field must contain either the username or the email address. -> - Any DataMiner Agent configured for SAML external authentication should be accessible via [**HTTPS**](xref:Setting_up_HTTPS_on_a_DMA). -> - For **DataMiner Cube**, prior to DataMiner 10.1.11/10.2.0, only the Administrator user can bypass the external authentication provider by entering an explicit username/password combination. In later DataMiner versions, this is also allowed for any local DataMiner user account. -> - For the **Web apps**, when external authentication is enabled, it is no longer possible to log in with local accounts. As a workaround, since you do not need to configure external authentication on every DMA of the cluster, you can log in to the web apps using external authentication on one DMA and log in using a local account on another DMA. +- For **DataMiner Cube**, it is possible to bypass the external authentication provider by entering an explicit username/password combination. However, prior to DataMiner 10.1.11/10.2.0, this is only possible for the Administrator user. -> [!CAUTION] -> If there are two DataMiner users who share the same email address, both users will not be able to log in. To prevent this from happening, we recommended not using more than one method to add users. For example, do not add Windows domain users if the Entra ID users use the same email address. +- For the **Web apps**, when external authentication is enabled, it is no longer possible to log in with local accounts. As a workaround, since you do not need to configure external authentication on every DMA of the cluster, you can log in to the web apps using external authentication on one DMA and log in using a local account on another DMA. > [!TIP] -> See also: [Authenticating Azure AD (i.e. Entra ID) users on DataMiner with SAML](https://community.dataminer.services/video/authenticating-azure-ad-users-on-dataminer-with-saml/) in the Dojo video library ![Video](~/user-guide/images/video_Duo.png) - -### Creating a DataMiner metadata file - -To create a DataMiner metadata file (also referred to as *Service Provider Metadata*), proceed as follows: - -1. Copy the following template into a new XML file named e.g. *spMetadata.xml*: - - From DataMiner 10.3.5 onwards: - - ```xml - - - - - - - ``` - - Older DataMiner versions: - - ```xml - - - - - - - - - - - - - ``` - - > [!NOTE] - > You can place the *spMetadata.xml* anywhere, as long as the *spMetadata* attribute for the *ExternalAuthentication* tag in *DataMiner.xml* points to the correct file. However, we recommend placing it in the `C:\Skyline DataMiner` folder. - -1. Replace \[ENTITYID\] with the unique service provider ID that is assigned to DataMiner when you register it with the identity provider. - - The way you can find this ID will depend on the identity provider you are using. See [Identity providers](#identity-providers). - -1. Replace ``https://dataminer.example.com`` with the IP address or the DNS name of your DataMiner System. Make sure the endpoint addresses in the location attributes match the DataMiner application endpoints you specified when you registered DataMiner with the identity provider. - - The way you configure this will depend on the identity provider you are using. See [Identity providers](#identity-providers). - -> [!NOTE] -> The ``WantAssertionsSigned`` flag is supported as from DataMiner version 10.2.1/10.2.0. If you are using an older version, then set this to false. SAML responses without signatures can be freely edited to tamper with permissions on the application, leading to severe vulnerabilities. We **highly recommend** setting ``WantAssertionsSigned`` to *true* to mitigate this. - -> [!IMPORTANT] -> From DataMiner 10.3.4/10.4.0 onwards, ``WantAssertionsSigned`` **must** be set to *true*. - -### Additional configuration for systems connected to dataminer.services - -When your DataMiner System is connected to dataminer.services, the following additional configuration is required for both the *spMetadata.xml* file and the identity provider: - -1. Specify the following URLs, replacing `` with the DNS name in the *spMetadata.xml* file and `` with the name of the organization: - - - `https://-.on.dataminer.services/API/` - - `https://-.on.dataminer.services/account-linking` - - `https://-.on.dataminer.services/account-linking/` - - > [!NOTE] - > Note the trailing "/". - - Example of remote access URL: - - In this example, the DMS DNS name is "dataminer" and the organization name is "skyline". - -1. Extend the *spMetadata.xml* file with the following code: - - ```xml - - - - ... - - - - - - ``` - -1. Update your provider settings. See [Identity providers](#identity-providers). - -## Identity providers - -DataMiner currently supports the following identity providers: - -- [Microsoft Entra ID](#microsoft-entra-id-formerly-azure-ad) -- [Azure B2C](#azure-b2c) -- [Okta](#okta) - -### Microsoft Entra ID (formerly Azure AD) - -DataMiner supports Entra ID (previously known as Azure Active Directory) as identity provider as from version 10.1.5. Entra ID is Microsoft's cloud-based identity and access management service, which helps users sign in and access resources. - -> [!NOTE] -> Prior to July 2023, Microsoft Entra ID was called Azure Active Directory. - -#### Setting up a Microsoft Entra ID Enterprise application - -From DataMiner 10.3.4/10.4.0 onwards, you must create an Enterprise Application in Entra ID when setting up external authentication. In earlier DataMiner versions from DataMiner 10.2.0/10.2.1 onwards, creating an Enterprise Application is highly recommended, as otherwise not all features will be available. - -> [!NOTE] -> Only a Global Administrator, Application Administrator, Cloud Application Administrator, and Application Developer have the necessary permissions to create Enterprise applications. - -1. In Entra ID, register DataMiner as an Enterprise Application: - - 1. Navigate to ``portal.azure.com`` and log in. - 1. Select the Azure Active Directory service. - 1. In the pane on the left, click *Enterprise applications*. - 1. At the top, click *New application*. - 1. Click *Create your own application*. - 1. Select *Integrate another application you don’t find in the gallery* and click *Create*. - -1. In the pane on the left, go to *Users and groups*. - -1. Add the necessary users and groups, and assign the necessary roles. - - > [!NOTE] - > Make sure that all users have their *Email* field filled in. Azure will not authenticate users with an empty *Email* field. - -1. Go to *Single sign-on*, select "SAML", and edit the following settings in *Basic SAML Configuration*: - - - Set *Entity ID* to the IP address or DNS name specified in the *spMetadata.xml* file, for example ``https://dataminer.example.com/``. - - - Under *Reply URL*, specify the following URL(s), replacing ``dataminer.example.com`` with the IP address or DNS name in the *spMetadata.xml* file (note the trailing "/"): - - From DataMiner 10.3.5 onwards: - - - ``https://dataminer.example.com/API/`` - - Older DataMiner versions: - - - ``https://dataminer.example.com/root/`` - - ``https://dataminer.example.com/ticketing/`` - - ``https://dataminer.example.com/jobs/`` - - ``https://dataminer.example.com/monitoring/`` - - ``https://dataminer.example.com/dashboard/`` - - ``https://dataminer.example.com/API/`` - - ``https://dataminer.example.com/`` - - - Set *Sign on URL* to the IP address or DNS name specified in the *spMetadata.xml* file, for example ``https://dataminer.example.com/``. - - > [!TIP] - > - See also: [Creating a DataMiner metadata file](#creating-a-dataminer-metadata-file) - > - See also: [Additional configuration for systems connected to dataminer.services](#additional-configuration-for-systems-connected-to-dataminerservices) - -#### Retrieving the identity provider's metadata file on Microsoft Entra ID - -In Entra ID, the ipMetadata URL can be found under *Single sign-on > SAML Signing Certificate – App Federation Metadata Url*. - -#### Configuring DataMiner to import users and groups from Microsoft Entra ID - -Once you have established a trust relationship between DataMiner (i.e. the service provider) and Entra ID (i.e. the identity provider), you can also configure DataMiner to import users and user groups from Entra ID. To do so, proceed as follows. - -1. Gather the following information: - - - **Client ID**, **Object ID**, and **Tenant ID**: These GUIDs identify the application (DataMiner) in the Entra ID platform, and identify the users & groups directory on the Azure portal, respectively. You can find these fields on the root page of the application: *Microsoft Entra ID > App registrations > [your application name]*. - - Creating an Enterprise Application will also create an app registration with the same name, but you will not find it under *owned application*. - - > [!IMPORTANT] - > Do not use the *Object ID* under *Azure Active Directory > Enterprise applications > [your application name]*. This is a different Object ID, which will not work. - - > [!NOTE] - > From DataMiner 10.3.11/10.4.0 onwards, the **Object ID** is optional. - - - **Client Secret**: In the pane on the left, click *Certificates & secrets*. - - 1. In the *Client secrets* section, click *New client secret*. - 1. Enter a description and an expiration date for the application secret. - 1. Copy the secret value for later on. - - > [!IMPORTANT] - > Once you leave this page, you will no longer be able to access the secret value. - - - **Username** and **Password**: The Entra ID user account that DataMiner will use to request data from Azure. Technically this can be any account, but we recommend that you create an account that will be use exclusively for this purpose. Note that, depending on the method of querying, specifying this account can be optional from DataMiner 10.1.11/10.2.0 onwards (see note below). - -1. Configure DataMiner with this information: - - 1. Stop the DMA for which you want to configure this. - - 1. On the DMA, go to the *C:\\Skyline DataMiner* folder and open the *DataMiner.xml* file. - - 1. In the *DataMiner.xml* file, specify the information you previously gathered using the same syntax as in the following example: - - ```xml - - ``` - - > [!NOTE] - > From DataMiner 10.1.11/10.2.0 onwards, DataMiner supports Entra ID application querying. If this is used instead of delegated querying, an authentication secret will suffice and no username and password will need to be specified here. - - 1. Save the file and restart DataMiner. - - > [!NOTE] - > As the client secret and password are sensitive data, after DataMiner has been restarted, this information is encrypted and replaced with a GUID in the *clientSecret* and *password* attributes of the *DataMiner.xml* file. - -1. On the application (DataMiner) root page, click *API Permissions* in the pane on the left and make sure the necessary permissions are enabled: - - For delegated querying: - - - Microsoft Graph \> Application.Read.All – Delegated – Read applications - - Microsoft Graph \> GroupMember.Read.All – Delegated – Read groups memberships - - Microsoft Graph \> User.Read – Delegated – Sign in and read user profile - - Microsoft Graph \> User.Read.All – Delegated – Read all users’ full profiles - - For application querying (supported from DataMiner 10.1.11/10.2.0 onwards): - - - Microsoft Graph \> Application.Read.All – Application – Read applications - - Microsoft Graph \> GroupMember.Read.All – Application – Read groups memberships - - Microsoft Graph \> User.Read.All – Application - Read all users’ full profiles - - Microsoft Graph \> User.Read – Delegated – Sign in and read user profile - -1. Add the Entra ID users to DataMiner: - - 1. Open DataMiner Cube and log in with an existing Administrator account. - 1. Add the users/groups as described in [Adding a user](xref:Adding_a_user) and [Adding a user group](xref:Adding_a_user_group). If you choose to add an existing user or group, you will be presented a list of all users and groups available on Entra ID. - 1. When you have added the necessary users, configure their permissions. See [Configuring a user group](xref:Configuring_a_user_group). - - It is now possible to log in to DataMiner with any of the Entra ID user accounts you have added, using either the domain and username (DOMAIN\\user) or the email address. - -#### Configuring automatic creation of users authenticated by Entra ID using SAML - -From DataMiner 10.2.0/10.1.12 onwards, users authenticated by Entra ID using SAML can be automatically created and assigned to groups in DataMiner. This is often referred to as JIT (Just-In-Time) Provisioning. - -1. Go to *Single Sign-on > Attributes & Claims* and add a group claim. - - > [!NOTE] - > If you add a group claim, the account name of the group will only be sent via SAML when the groups are synchronized. Otherwise, the ID of the group will be sent instead. - -1. In DataMiner Cube, add the groups corresponding with the groups you added in Entra ID. See [Adding a user group](xref:Adding_a_user_group). - -1. Stop DataMiner. - -1. Go to the *C:\\Skyline DataMiner* folder and open the *DataMiner.xml* file. - -1. In the *DataMiner.xml* file, configure the *\* tag as illustrated in the example below: - - ```xml - - ... - - - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname - [group claim name] - - - ... - - ``` - - > [!NOTE] - > - > - User groups have to exist in DataMiner both for *Groups* claims set to true and to false. Make sure all the necessary groups have been added earlier, so that it will be possible to add users to them. - > - If you set the *claims* attribute of the *Groups* element to "false", no claims will be used to add users to groups. In this case: - > - Instead of a claim for user groups, replace `[group claim name]` with a security group that exists in DataMiner as described above. - > - It will only be possible to add a user to a single group. - > - The user information that is created will not be updated. - -1. Save the *DataMiner.xml* file. - -1. Restart the DataMiner Agent. - -> [!NOTE] -> If your default username is not in email format or if DataMiner is unable to locate it, configure the *\* tag to ensure it points to the correct email address. - -### Azure B2C - -DataMiner supports Azure B2C as identity provider from version 10.2.6/10.3.0 onwards. To configure this: - -1. Configure Azure B2C. See [Azure Active Directory B2C documentation | Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory-b2c/). -1. Create a DataMiner metadata file. You can do this in the same way as for [Entra ID](#creating-a-dataminer-metadata-file). -1. Set up an Entra ID Enterprise application. You can do this in the same way as for [Entra ID](#setting-up-a-microsoft-entra-id-enterprise-application). -1. Configure policies for Azure B2C. See [Tutorial: Create user flows and custom policies in Azure Active Directory B2C | Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-custom-policy). -1. Get the metadata URL: - - 1. In Azure, go to *App registrations*, select your app, and select *Overview* > *Endpoints*. - 1. Select the Azure AD B2C SAML metadata endpoint, e.g. `https://dataminerservices.b2clogin.com/dataminerservices.onmicrosoft.com//Samlp/metadata`, and replace \ with the name of the policy you created earlier. - -1. Configure DataMiner to automatically create users from Azure B2C. You can do this in the same way as for [Entra ID](#configuring-automatic-creation-of-users-authenticated-by-entra-id-using-saml). For the ipMetadata link, use the link created in the previous step. - - > [!NOTE] - > To create SAML users in DataMiner using Azure B2C, a domain is required in the usernames. For this reason, email addresses must be used as the usernames. If the default username of the identity provider is not a valid email address, add a \ element to the \ element in *DataMiner.xml* that refers to a claim containing a valid email address. - -### Okta - -DataMiner supports Okta as identity provider as from version 10.1.11. Use Okta's App Integration Wizard to create a new app integration and connect Okta with DataMiner. - -> [!IMPORTANT] -> -> - Prior to DataMiner 10.3.0/10.3.2, it may not be possible to log in using Okta because of a software issue. We strongly recommend that you upgrade to DataMiner 10.3.0 or 10.3.2 to use this feature. -> - When Okta is used, automatic user creation must be enabled. It is currently not possible to import users and groups from Okta. Alternatively, you can add local or domain users. See [User directories](xref:User_management#user-directories) and [Local users](xref:User_management#local-users). After that, you can have Okta authenticate these users by following the guide below, except that you omit the *AutomaticUserCreation* tag in *DataMiner.xml*. - -1. Launch the App Integration Wizard - - 1. In the Admin Console, go to *Applications \> Applications*. - 1. Click *Create App Integration*. - 1. To create a SAML integration, select "SAML 2.0" as the *Sign-on method*. - 1. Click *Next*. - -1. Configure the general settings: - - - **App name**: The name of your application. Fill in “DataMiner” (or some other preferred name). - - - **App logo**: Optional logo to be linked to your application. - - - Format: PNG, JPG or GIF - - Max. size: 1 MB - - Min. resolution: 420 x 120 pixels - - > [!TIP] - > It is recommended to use a PNG image with a transparent background and a landscape orientation. - -1. Configure the Okta SAML settings: - - - **Single sign on URL**: The location where the SAML assertion is sent with a POST operation. - - - In this box, enter e.g. ``https://dataminer.example.com/root/``. - - Select the following checkboxes: - - - *Use this for Recipient URL and Destination URL* - - *Allow this app to request other SSO URLs* - - - Open *Show Advanced Settings* and enter the following additional URLs to *Other Requestable SSO URLs*: - - From DataMiner 10.3.5 onwards: - - ``https://dataminer.example.com/API/`` - - Older DataMiner versions: - - ``https://dataminer.example.com/root/`` - - ``https://dataminer.example.com/API/`` - - ``https://dataminer.example.com/dashboard/`` - - ``https://dataminer.example.com/monitoring/`` - - ``https://dataminer.example.com/jobs/`` - - ``https://dataminer.example.com/ticketing/`` - - > [!NOTE] - > The indexes here should be the same as the indexes in `C:\Skyline DataMiner\okta-sp-metadata.xml`, which we will create in a further step. - - > [!TIP] - > See also: [Additional configuration for systems connected to dataminer.services](#additional-configuration-for-systems-connected-to-dataminerservices) - - - **Audience URI (SP Entity ID)**: The intended audience of the SAML assertion. - - In this box, enter ``https://dataminer.example.com/``. - - - **Name ID format**: The username format you are sending in the SAML Response. - - Select "EmailAddress". - - - **Application username**: The default value to use for the username with the application. - - Select "Email". - - - **Attribute Statements**: Add the following attribute statements, all with "Basic" format: - - - name "Email", value "user.email" - - name "Firstname", value "user.firstName" - - name "Lastname", value "user.lastName" - - - **When using group claims:** - - - Create groups in DataMiner with the exact same names as in Okta (this is case-sensitive). See [Adding a user group](xref:Adding_a_user_group). - - Add a group attribute statement. - - Use the name "userGroups", and "Basic" format. - - Under *Filter*, select the type of filter you want, and then add a statement that will match the groups you want to send for that user. - - > [!Note] - > - > - The name fields can be anything you want, but we recommend giving them a name that clearly reflects the claim they refer to. All of these are case-sensitive. - > - Make sure that what you put under "name" for each claim matches exactly with the claim names in *DataMiner.xml*. - -1. Stop DataMiner. - -1. Go to the *C:\\Skyline DataMiner* folder and open the *DataMiner.xml* file. - -1. In the *DataMiner.xml* file, configure the *\* tag as illustrated in the example below: - - ```xml - - ... - - - [email claim name] - [firstname claim name] - [lastname claim name] - [group claim name] - - - ... - - ``` - - > [!NOTE] - > - > - The claim name refers to the attribute statement names that were added in Okta. - > - User groups have to exist in DataMiner both for *Groups* claims set to true and to false. Make sure all the necessary groups have been added earlier, so that it will be possible to add users to them. - > - If you set the *claims* attribute of the *Groups* element to "false", no claims will be used to add users to groups. In this case: - > - Instead of a claim for user groups, replace `[group claim name]` with a security group that exists in DataMiner as described above. - > - It will only be possible to add a user to a single group. - > - The user information that is created will not be updated. - -1. Save the *DataMiner.xml* file. - -1. Open the *Sign On* tab of your Okta application and scroll down to *SAML Signing Certificates*. - -1. In the *Actions* column of the *Active* certificate, click *View IdP metadata*. - -1. Save this identity provider’s metadata XML file to the DataMiner Agent, e.g. `C:\Skyline DataMiner\okta-ip-metadata.xml`. - -1. Copy the following template to a new XML file named e.g. `C:\Skyline DataMiner\okta-sp-metadata.xml` to create the service provider’s metadata file. You can find the EntityID in the previously created file `C:\Skyline DataMiner\okta-ip-metadata.xml`. - - From DataMiner 10.3.5 onwards: - - ```xml - - - - - - - ``` - - Older DataMiner versions: - - ```xml - - - - - - - - - - - - ``` - -1. Restart DataMiner. +> See also: [Troubleshooting SAML issues](xref:Troubleshooting_SAML_Issues) diff --git a/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Setting_up_Azure_Active_Directory_Domain_Services.md b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Setting_up_Azure_Active_Directory_Domain_Services.md index a99bc1a2a0..8e8a89f7cf 100644 --- a/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Setting_up_Azure_Active_Directory_Domain_Services.md +++ b/user-guide/Advanced_Functionality/Security/Advanced_security_configuration/Setting_up_Azure_Active_Directory_Domain_Services.md @@ -4,7 +4,7 @@ uid: Setting_up_Azure_Active_Directory_Domain_Services # Setting up Azure Active Directory Domain Services -The recommended way to connect your DataMiner System with Microsoft Entra ID (formerly known as Azure AD) is via SAML. See [Configuring external authentication via an identity provider using SAML](xref:Configuring_external_authentication_via_an_identity_provider_using_SAML). However, if this is not possible, you also have the possibility to connect via LDAP. To do so, you will first need to deploy the Azure AD Domain Services and then configure the DNS servers. +The recommended way to connect your DataMiner System with Microsoft Entra ID (formerly known as Azure AD) is via SAML. See [Configuring SAML settings](xref:Configuring_external_authentication_via_an_identity_provider_using_SAML). However, if this is not possible, you also have the possibility to connect via LDAP. To do so, you will first need to deploy the Azure AD Domain Services and then configure the DNS servers. ### Deploying the Azure AD DS diff --git a/user-guide/Advanced_Functionality/toc.yml b/user-guide/Advanced_Functionality/toc.yml index 0db4023c17..e7e37fc80c 100644 --- a/user-guide/Advanced_Functionality/toc.yml +++ b/user-guide/Advanced_Functionality/toc.yml @@ -517,14 +517,25 @@ items: topicUid: HTTP_Headers - name: Disabling legacy protocols topicUid: Disabling_legacy_protocols + - name: Configuring SAML settings + topicUid: Configuring_external_authentication_via_an_identity_provider_using_SAML + items: + - name: Configuring SAML with Microsoft Entra ID + topicUid: SAML_using_Entra_ID + - name: Configuring SAML with Azure B2C + topicUid: SAML_using_Azure_B2C + - name: Configuring SAML with Okta + topicUid: SAML_using_Okta + - name: Additional configuration for systems connected to dataminer.services + topicUid: SAML_config_to_connect_to_cloud + - name: Troubleshooting SAML issues + topicUid: Troubleshooting_SAML_Issues - name: Configuring LDAP settings topicUid: Configuring_LDAP_settings - name: Configuring Atlassian Crowd settings topicUid: Configuring_Atlassian_Crowd_settings - name: Configuring RADIUS settings topicUid: Configuring_RADIUS_settings - - name: Configuring external authentication via an identity provider using SAML - topicUid: Configuring_external_authentication_via_an_identity_provider_using_SAML - name: Setting up Azure Active Directory Domain Services topicUid: Setting_up_Azure_Active_Directory_Domain_Services - name: Enabling TLS encryption diff --git a/user-guide/Cloud_Platform/Connecting_to_cloud/Connect_to_cloud_requirements.md b/user-guide/Cloud_Platform/Connecting_to_cloud/Connect_to_cloud_requirements.md index ebc2bc297a..e43ccac35f 100644 --- a/user-guide/Cloud_Platform/Connecting_to_cloud/Connect_to_cloud_requirements.md +++ b/user-guide/Cloud_Platform/Connecting_to_cloud/Connect_to_cloud_requirements.md @@ -21,7 +21,7 @@ Before connecting your DataMiner System to dataminer.services, verify that the f > **At least one DMA** in the DMS must be able to reach these endpoints. On DMAs that **do not allow network traffic** towards `*.dataminer.services`, make sure **DataMiner CloudGateway is not installed**. From DataMiner 10.3.7/10.4.0 onwards, a Cloud Pack without DataMiner CloudGateway is installed by default when you upgrade or install DataMiner. In earlier DataMiner versions, if you install the Cloud Pack on additional DMAs that do not allow network traffic towards `*.dataminer.services`, after the installation, uninstall DataMiner CloudGateway on those DMAs. See [uninstalling a program in Windows](https://support.microsoft.com/en-us/windows/uninstall-or-remove-apps-and-programs-in-windows-4b55f974-2cc6-2d2b-d092-5905080eaf98). > [!TIP] - > Using SAML? See also: [Additional configuration for systems connected to dataminer.services](xref:Configuring_external_authentication_via_an_identity_provider_using_SAML#additional-configuration-for-systems-connected-to-dataminerservices) + > Using SAML? See also: [Additional configuration for systems connected to dataminer.services](xref:SAML_config_to_connect_to_cloud) - The **internal network must allow [HTTP(S) traffic via port TCP 5100](xref:Configuring_the_IP_network_ports#overview-of-ip-ports-used-in-a-dms)**. For more information about configuring this endpoint, see [Custom dataminer.services endpoint configuration](xref:Custom_cloud_endpoint_configuration). diff --git a/user-guide/Troubleshooting/Procedures/Troubleshooting_procedures.md b/user-guide/Troubleshooting/Procedures/Troubleshooting_procedures.md index 5ed0c35deb..10f10ffbec 100644 --- a/user-guide/Troubleshooting/Procedures/Troubleshooting_procedures.md +++ b/user-guide/Troubleshooting/Procedures/Troubleshooting_procedures.md @@ -16,6 +16,7 @@ uid: Troubleshooting_procedures - ['Sharing dashboard' window does not disappear](xref:Sharing_dashboard_window_does_not_disappear) -- [Troubleshooting SAML issues](xref:Troubleshooting_SAML_Issues) - - [Manually removing old alarms from an Elasticsearch cluster](xref:Manually_removing_old_alarms_from_ES) + +> [!TIP] +> See also: [Troubleshooting SAML issues](xref:Troubleshooting_SAML_Issues) diff --git a/user-guide/Troubleshooting/toc.yml b/user-guide/Troubleshooting/toc.yml index a3f67b4e0c..1650c77477 100644 --- a/user-guide/Troubleshooting/toc.yml +++ b/user-guide/Troubleshooting/toc.yml @@ -197,8 +197,6 @@ items: topicUid: Keeping_a_DMA_from_running_out_of_disk_space - name: Sharing dashboard window does not disappear topicUid: Sharing_dashboard_window_does_not_disappear - - name: Troubleshooting SAML issues - topicUid: Troubleshooting_SAML_Issues - name: Manually removing old alarms from an Elasticsearch cluster topicUid: Manually_removing_old_alarms_from_ES - name: Known issues diff --git a/user-guide/images/SAML_Add_client_secret.png b/user-guide/images/SAML_Add_client_secret.png new file mode 100644 index 0000000000..af8f4c45e2 Binary files /dev/null and b/user-guide/images/SAML_Add_client_secret.png differ diff --git a/user-guide/images/SAML_Add_enterprise_app.png b/user-guide/images/SAML_Add_enterprise_app.png new file mode 100644 index 0000000000..faafd28ca3 Binary files /dev/null and b/user-guide/images/SAML_Add_enterprise_app.png differ diff --git a/user-guide/images/SAML_Add_group_claim.png b/user-guide/images/SAML_Add_group_claim.png new file mode 100644 index 0000000000..aee8db0832 Binary files /dev/null and b/user-guide/images/SAML_Add_group_claim.png differ diff --git a/user-guide/images/SAML_Add_users_groups.png b/user-guide/images/SAML_Add_users_groups.png new file mode 100644 index 0000000000..f3da7926f6 Binary files /dev/null and b/user-guide/images/SAML_Add_users_groups.png differ diff --git a/user-guide/images/SAML_B2C_endpoints.png b/user-guide/images/SAML_B2C_endpoints.png new file mode 100644 index 0000000000..a3c46b2415 Binary files /dev/null and b/user-guide/images/SAML_B2C_endpoints.png differ diff --git a/user-guide/images/SAML_Edit_claim.png b/user-guide/images/SAML_Edit_claim.png new file mode 100644 index 0000000000..6b8115f2c2 Binary files /dev/null and b/user-guide/images/SAML_Edit_claim.png differ diff --git a/user-guide/images/SAML_Group_claim_config.png b/user-guide/images/SAML_Group_claim_config.png new file mode 100644 index 0000000000..598bdf4313 Binary files /dev/null and b/user-guide/images/SAML_Group_claim_config.png differ diff --git a/user-guide/images/SAML_New_client_secret.png b/user-guide/images/SAML_New_client_secret.png new file mode 100644 index 0000000000..c87bb1c475 Binary files /dev/null and b/user-guide/images/SAML_New_client_secret.png differ diff --git a/user-guide/images/SAML_Reply_URLs.png b/user-guide/images/SAML_Reply_URLs.png new file mode 100644 index 0000000000..85b964d6e7 Binary files /dev/null and b/user-guide/images/SAML_Reply_URLs.png differ diff --git a/user-guide/images/SAML_application_info.png b/user-guide/images/SAML_application_info.png new file mode 100644 index 0000000000..1d8f4358a3 Binary files /dev/null and b/user-guide/images/SAML_application_info.png differ diff --git a/user-guide/images/SAML_edit_basic_config.png b/user-guide/images/SAML_edit_basic_config.png new file mode 100644 index 0000000000..e57d0c11bc Binary files /dev/null and b/user-guide/images/SAML_edit_basic_config.png differ