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 or domain users 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.

Launch Okta's App Integration Wizard.
1. In the Admin Console, go to Applications > Applications.
2. Click Create App Integration.
3. To create a SAML integration, select "SAML 2.0" as the Sign-on method.
4. Click Next.
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.
Configure the Okta SAML settings and the user groups:
- 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 <dms-dns-name> with the DNS name of the DataMiner System and <organization-name> with the name of the organization
    - https://<dms-dns-name>-<organization-name>.on.dataminer.services/API/
    - https://<dms-dns-name>-<organization-name>.on.dataminer.services/account-linking
    - https://<dms-dns-name>-<organization-name>.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
- 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.
  - 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.
- When not using group claims, create a group in DataMiner to which users will be added when they log in. You can for instance name it Auto-imported users.
Stop DataMiner.
Go to the C:\Skyline DataMiner folder and open the DataMiner.xml file.
In DataMiner.xml, configure the <ExternalAuthentication> tag as detailed below:
- When using group claims, set the claims attribute of the Groups element to "true", and add the name of the SAML attribute that will contain the group names in the XML element (i.e. userGroups):
```
<DataMiner ...>
  ...
  <ExternalAuthentication
    type="SAML"
    ipMetadata="[Path/URL of the identity provider’s metadata file]"
    spMetadata="[Path/URL of the service provider’s metadata file]"
    timeout="300">
    <AutomaticUserCreation enabled="true">
      <EmailClaim>[email claim name]</EmailClaim>
      <Givenname>[firstname claim name]</Givenname>
      <Surname>[lastname claim name]</Surname>
      <Groups claims="true">userGroups</Groups>
    </AutomaticUserCreation>
  </ExternalAuthentication>
  ...
</DataMiner>
```
- When not using group claims, set the claims attribute of the Groups element to "false", and add the name of the DataMiner group into which users will be imported in the XML element (e.g. Auto-imported users):
```
<DataMiner ...>
  ...
  <ExternalAuthentication
    type="SAML"
    ipMetadata="[Path/URL of the identity provider’s metadata file]"
    spMetadata="[Path/URL of the service provider’s metadata file]"
    timeout="300">
    <AutomaticUserCreation enabled="true">
      <EmailClaim>[email claim name]</EmailClaim>
      <Givenname>[firstname claim name]</Givenname>
      <Surname>[lastname claim name]</Surname>
      <Groups claims="false">[DataMiner user group]</Groups>
    </AutomaticUserCreation>
  </ExternalAuthentication>
  ...
</DataMiner>
```
Note
- The claim name refers to the attribute statement names that were added in Okta.
- In both setups, user groups have to exist in DataMiner, so make sure these have been added. In case group claims are used, make sure all the necessary groups have been added, as users can only be added in DataMiner if the groups they belong to also exist in DataMiner. Also, keep in mind that the group names are case-sensitive.
- When no group claims are used, it will only be possible to add a user to a single group, and the user information that is created will not be updated.
- Group membership is synced on each login. This means that if, for example, you manually add an OKTA user to the Administrators group, and that group is not specified in the groups claims on the next login, the user will be removed again.
Save the DataMiner.xml file.
Open the Sign On tab of your Okta application and scroll down to SAML Signing Certificates.
In the Actions column of the Active certificate, click View IdP metadata.
Save this identity provider’s metadata XML file to the DataMiner Agent, e.g. C:\Skyline DataMiner\okta-ip-metadata.xml.

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 version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="[ENTITYID]" validUntil="2050-01-04T10:00:00.000Z">
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dataminer.example.com/API/" index="0" isDefault="false"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Older DataMiner versions:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="[ENTITYID]" validUntil="2050-01-04T10:00:00.000Z">
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dataminer.example.com/API/" index="0" isDefault="false"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dataminer.example.com/root/" index="1" isDefault="false"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dataminer.example.com/dashboard/" index="2" isDefault="false"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dataminer.example.com/monitoring/" index="3" isDefault="false"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dataminer.example.com/jobs/" index="4" isDefault="false"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dataminer.example.com/ticketing/" index="5" isDefault="false"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

For a DMA connected to dataminer.services, add the three following additional bindings within the <md:SPSSODescriptor> element:

  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    ...
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<dms-dns-name>-<organization-name>.on.dataminer.services/API/" index="1" isDefault="true"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<dms-dns-name>-<organization-name>.on.dataminer.services/account-linking" index="2" isDefault="false"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<dms-dns-name>-<organization-name>.on.dataminer.services/account-linking/" index="3" isDefault="false"/>
  </md:SPSSODescriptor>

Restart DataMiner.

Table of Contents

Configuring SAML with Okta as the identity provider

Important

Note

Tip

Note

Tip

Note

Note