Introduction

Octopus can connect to Microsoft Entra ID to facilitate access to the application.

Using an identity federator provides an integrated login experience to your Octopus environment. Your users and technicians won't need to create a new password to use Octopus applications.

IMPORTANT: Mode available for hosted customers only.

Octopus can connect to a federated identity manager to ease access to the application in a hosted environment.

Single sign-on can be used independently for the following components, depending on what your federation provider supports:

• Web Portals for end users. 
• Applications meant for technicians (Windows client (WinUI), WebTech and Octopus Web / Rest API).

Prerequisites

• An Active Directory domain (on site, i.e. installed on a Windows server in your infrastructure)

• A Microsoft Entra ID subscription

• A hybrid cloud domain (updated via AD Connect)
• Active synchronization of your users between your domain and Octopus
  • Via ADSIReader from your Active Directory domain to Octopus 
• A good knowledge of Microsoft Entra ID Enterprise Applications

How it works

Web portal

When your end users arrive on your web portal for the first time, they will be automatically redirected to your Microsoft Entra ID authentication page, as configured by you. They will be invited to authenticate to your domain. The experience will be very similar to that experienced when users try to access Microsoft resources in your environment (such as Outlook or Sharepoint).

Once they have completed the authentication process, they will be automatically redirected to the Octopus web portal and automatically authenticated.

Windows Applications

Windows Client for Technicians (WinUI) 

When the Windows application is launched, a Microsoft Entra ID login window will appear. The user will be prompted to authenticate with the user they wish to use to log into Octopus. Once authentication is complete, the Windows application will be launched and authenticated with the selected user.

Batch applications (MailIntegration, DataImporter, ADSIReader, etc.)

It is important to understand that the unique authentication of a batch application, launched by a Windows task, takes place in the context of the Windows user configured in the Windows task.

There are two ways of configuring authentication for these applications: 

1. Via  standard authentification settings (/login - /password)
   • You will need to provide the username/password of the user's Microsoft Entra ID account.
   • The authentication information will then be in plain text in your configuration (batch file or command line).
     • The password can be encrypted (see Tools | Generate encrypted password for Entra ID).
2. Via user name setting d'utilisateur (/login)
   • Log in to your Windows session and launch the batch application
   • You will then be able to authenticate the user correctly in Microsoft Entra ID, and subsequent authentications will be carried out automatically.
   • All you need to do is specify the user name as a parameter to ensure that the application authenticates correctly

User UPN synchronization

Octopus allows users' UPNs to be synchronized automatically, making it easier to manage these identifiers. This synchronization can be done automatically via the ADSIReader application. . 

Once UPN synchronization is up and running, you'll find a new Windows username in each user file, corresponding to each user's UPN. Note that an Octopus user can have multiple Windows usernames. The semicolon (;) is the character that delimits each user name.

ADSIReader configuration

• Identify where ADSIReader is running
• Open the folder where the executable is located
• Make a copy of the ADSIReaderLDAPMappings.xml file and put this copy in a other folder than the Octopus folder.
• Modify this file to add the following XML element::
  • <attribute LDAPAttribute="userPrincipalName" OctopusAttribute="UPN"/>
  • This new element must be under the <mapping Name="User"> element, at the same level as the objectGUID, sAMAccountName, etc. attributes.
  • Save file
  • Note the path to this modified file
• Modify the existing ADSIReader command line to add the following setting: :
  • /MappingsFilePath:"[Path of modified file ADSIReaderLDAPMappings.xml]"
• For further information : ADSIReader - Importation à partir d'Active Directory

Alternative

If using ADSIReader isn't possible, there's an alternative that uses DataImporter. The general idea here is to export all your users present in Microsoft Entra ID and prepare an Excel file.

Once the Excel file is ready, you can use DataImporter to upload this information to Octopus.

Exporting users from Microsoft Entra ID

You will need to set up a script (probably Powershell) that will obtain the list of your users and prepare an Excel file with at least the following columns:  : 

• First name
• Last name
• Email
• UPN

Importing users into Octopus

Once you've obtained the Excel file in the previous step, you'll need to import this information using DataImporter.

For more detail : DataImporter - Importing users

UPN authentification test

Once you have synchronized your users' UPNs, test that you are able to authenticate in Octopus using your UPN.

• Launch Octopus
• Enter a UPN as user name
  • This should look like an e-mail address:  : username@domaine.com
• Set current Octopus password

Alternative authentification for emergency

Octopus allows users with "Can administer Octopus" permission to authenticate directly in Octopus, bypassing the built-in authentication. This allows an administrator to access Octopus in the event of a problem with the identity federator configuration.

Steps for using alternative authentication as a emergency

1. Press the SHIFT  key (MAJUSCULE) on your keyboard
2. While the SHIFT key (MAJUSCULE)  is pressed, launch the Windows Octopus client (WinUI).
3. Hold down the SHIFT key until the Octopus authentication window appears.
4. Release SHIFT key (MAJUSCULE)
5. Enter your username (probably your UPN if synchronization has been set up correctly) and the Octopus password you were using before.
   * This password is not the same as your domain password.

Configuring Microsoft Entra ID

To connect Octopus and Microsoft Entra ID, an Enterprise Application must be properly configured for integrated authentication.

Creating an enterprise application

• Open the Microsoft Entra ID administration portal and navigate to the Enterprise Applications panel.
  • https://aad.portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview
• Click on + New Application
• Click on + Create your own application
• Enter a suitable name
• Select the option Integrate any other application you don't find in the gallery (Non-gallery)
• Press  the Create button

Single sign-on configuration 

Before proceeding further, please note down the application identifier (App ID). You will need it later.

Single sign-on for the web portal uses the SAML method.

From the main page of the enterprise application created in the previous step :

• Click on button 2. Configure single sign-on
• Click on the SAML button
• Click on the "Edit" button of the Basic SAML Configuration section and fill the following fields:
  1. Identifier (Entity ID) :
     • https://[nameofyourenvironment].octopus-itsm.com

  2. Reply URL (Assertion Consumer Service URL) :

     • https://[nameofyourenvironment].octopus-itsm.com

  3. Sign on URL :

     • https://[nameofyourenvironment].octopus-itsm.com/web/login.aspx​
  4. ​Click on the Save button at the top
• In the attributes and claims section 
  • The following claims are required:
    • givenName
    • surname
    • emailaddress
    • name
    • Unique User Identifier
  • The default values shown here are the correct ones.

Application registration configuration

These configurations are necessary for Octopus applications to work properly.

Addition of the Desktop and Mobile Applications platform

• Go to application registration (See procedure in annex)
• Click on Authentication in the Manage section
• Click on +  Add a platform
• Click on Mobile and desktop applications
• Check  https://login.microsoftonline.com/common/oauth2/nativeclient
• Click on Configure to save changes
• Scroll down to Advanced settings
• Set the option Allow public client flows to Yes
• Click on the Save button at the bottom of the page

Authorization configuration

1. Click on Click on the API permission item in the Manage section
2. Click on the + Add a permission button
3. Click on Microsoft APIs
4. Click in Microsoft Graph
5. Click on Delegated permissions
6. In the "OpenId permissions" section
   • Check openid Sign users in 
7. Click on Add permissions

Administrator consent

• Click on Grant admin consent for [Your Azure tenant name]. 
• Confirm consent

Users authorization

Each user of your Microsoft Entra ID must be added to the newly created enterprise application. There are two possible choices:

1. Autorisation Authorization for all users in your company
2. Manual user selection

Authorization for all users in your company

To make this application available to all your users, you can disable the required user assignment for this application

• Access the Enterprise application configuration (See procedure in annex)
• Click on the Properties item in the Manage section
• Change the value of the property Required assignment? to No

​It may take a few minutes for the configuration to be taken into account by the authentication system.

Manuel user selection

• Access the Enterprise application configuration (See procedure in annex)
• Click on the Users and groups item in the Manage section
• Add users / groups according to your needs

It may take a few minutes for the configuration to be taken into account by the authentication system.

Configuration for Octopus Web / Rest API

This step is optional and may not be necessary in your environment.

If your Octopus environment allows the use of Octopus Web (also known as Octopus 5) or Rest APIs, you will need to configure a second enterprise application in Microsoft Entra ID.

Make a note of the application ID that was created in this article. It will be needed to configure Octopus later.

To complete the configuration, please continue to the article Identity Federation - Microsoft Entra ID - API Application.

Octopus configuration

Only an Octopus administrator with the following access rights can complete the Octopus configuration: 

• General - Administer Octopus.
• General - Modify common team data.
• Applications - Access the Web Portal.
• Applications - Access to Octopus.
• Applications - Access Web Tech.

Prerequisites

Initial validation

Before continuing here, ensure that your Octopus environment is NOT configured for Octopus Web / REST API.

1. Launch the Octopus windows client
2. Go to Tools > Identity Federation Configuration
3. Check the API Application Section
   • ​​Validate that the fields or this section are disabled (grayed out)
   • Validate that the following message is shown "This section applies if you are using Octopus Web or REST APIs."

​If the API Application section is enabled and you do not see the message above, this means that Octopus 5 / REST APIs are enabled in your environment. You therefore need to continue with this article : Identity Federation - Microsoft Entra ID - API Application

Identity federation configuration

Validation

To start configuration, use the Tools > Identity federation configuration menu.

1. Fill your Directory (tenant) ID into the field Azure Directory (tenant) ID.
2. Fill the identifier of the application (the one you noted in the previous step) into the Azure Application (client) ID field of the SAML - OpenID application section

3. Click on Verify compatibility

The Microsoft Entra ID authentication window for your company may appear. If so, select your account (it must have access to Octopus).

When the verification is complete, the status icons will change from a ? (Compatibility not verified) to a green check mark.

Authentication scope

Select the desired scope of federated authentication: 

• Web Portal authentication mode
  • To have your end users authenticate automatically, select Federated identity. 
  • You can return to the previous authentication mode at any time by selecting Return to mode 2: Username; Password.
• Assignee authentication mode
  • To have your technicians (using the Windows application) and Batch tools (MailIntegration, ADSIReader, DataImporter, etc.) authenticate themselves automatically, select Federated Identity.
  • You can return to the previous authentication mode at any time by selecting Return to mode 0: Username; Password.

Annex

How to find the enterprise application

1. Open the main Microsoft Entra ID admintration console
   • Microsoft Entra admin center (Enterprise applications - Microsoft Entra admin center)
2. Click on the Application registrations
3. Click on All applications
4. In the search box, enter the name used to create the enterprise application
5. Select the application created