Identity Federation

SHOW ALL CONTENT

Table of contents

Introduction

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 users. 
  • Applications meant for assignees (Windows client (WinUI), WebTech and Octopus5).
WARNING:

Prior to considering this solution, make sure you have available resources and expertise to implement and support identity federation. 

The required technical knowledge lies outside of our field of expertise.

Prerequisites

To enable integrated logon, you need to provide a federation infrastructure compliant with the following requirements:

  • Use an Identity provider supported by Octopus.
    • Active Directory Federation Services 3.0, which supports both the Web Portal and the assignee applications.
    • Azure Active Directory Federation Services 3.0, limited to the Web Portal for users.
  • Enable the appropriate technical configurations. 
    • Make your identity federation provider available on the Web.
    • Activate required endpoints for all required applications.
    • Configure your identity federation provider to trust the required relying parties.
    • Use an SSL certificate that is valid for all machines that will be using federated identity.
  • Adjust your business processes to support your use of federated identities.
    • Make sure there is a match between Octopus and federated identities.
    • Configure desktops to support single sign-on.

Identity federation configuration possibilities being endless, Octopus cannot offer technical support on setting up these requirements; you must make sure that you have an internal resource with the appropriate knowledge.

How Identity Federation works

When you are using integrated authentication, Octopus is no longer responsible for authenticating users.  

When a user attempts to connect, Octopus will forward the authentication request to your identity federation manager, and wait until it provides a session token. 

The user's system will then automatically use the session token to authenticate in Octopus. If the user is recognized by your identity federation manager but doesn't exists in Octopus, it will automatically be created and assigned to the default group End User (Web Portal) and will have access to your Web Portal.

Each application uses different authentication endpoints that must be supported:

  • General configuration
    • Federation Metadata [/FederationMetadata/2007-06/FederationMetadata.xml].
  • Web Portal
    • SAML2.0/WS-Federation [/adfs/ls or /wsfed].
  • WinUI
    • WS-Trust 1.3 - Kerberos [/adfs/service/trust/13/kerberosmixed].
    • WS-Trust 1.3 - Password [/adfs/services/trust/13/usernamemixed].
  • Octopus 5
    • OAuth2 [/adfs/oauth2/authorize].
    • OAuth2 [/adfs/oauth2/token].

The session token submitted to Octopus by your identity federation manager must contain the following claims:

  • name
    • Corresponds to the Windows Username field in Octopus.
    • Corresponds normally to the sAMAccountName attribute in Active Directory.
    • This field is used to establish the link between the identity provided by the manager and Octopus.
    • This claim is mandatory.
  • givenname
    • Corresponds to the First Name field in Octopus.
    • Corresponds normally to the givenName attribute in Active Directory.
    • This claim is mandatory but is not used for any validation.
  • surname
    • Corresponds to the Last Name field in Octopus.
    • Corresponds normally to the sn attribute in Active Directory.
    • This claim is mandatory but is not used for any validation.
  • emailaddress
    • Corresponds to the Professional Email field in Octopus.
    • Corresponds normally to the mail attribute in Active Directory.
    • This claim is optional and not used for any validation.

Octopus Configuration

Once your federation manager is in place, you need to follow this procedure to finish setting up Octopus.

Activating integrated authentication is available only once your identity federation server has been tested.

Only an Octopus administrator with the following permissions is able to modify the Identity Federation parameters:

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

To access the configuration, use the Tools > Identity Federation Configuration menu.

Visual Explanation

In the Identity Federation configuration window, you will find the link providing the Octopus Metadata to help you configure your Relying Party in ADFS. It is normal that this URL cannot be accessed directly.

You will be able to enter the address of your Federation Metadata file to verify its compatibility. The compatibility check will establish a connection to the Metadata service to determine what compatible endpoints are available before testing each one.

Once verification is complete, you will be able to activate federated identity independently for the users (Web Portal) or for assignee applications (WinUI, WebTech and Octopus 5).

 

Configuring ADFS 3.0 Relying Party

Generally, ADFS Relying Parties must be configured as such:

  • Have a relying party for each environment you are using (production, test).
    • https://clientname.octopus-itsm.com.
    • https://clientname-test.octopus-itsm.com.
  • Manually create a relying party for each legacy URL that you are using.  If you do not use any legacy URL, you do not have to create those.
    • https://app.octopus-itsm.com.
    • https://app1.octopus-itsm.com.
    • https://app3.octopus-itsm.com.
    • https://app4.octopus-itsm.com.
  • Each relying party must refer to a single URL endpoint.
  • Each  relying party must use the WS-Federation Passive protocol.

  • No relying party must encrypt it's token.
  • Octopus offers a Metadata service that allows you to easily configure a relying party.

 

Relying Party Configuration

NOTE:

The use of multiple authentication factors, authorization restrictions, changes to claims rules, and aggregation of multiple identity sources is beyond the scope of this procedure. Refer to your identity federation specialist for more information.

To configure a Relying Party using the least amount of feature, use the following procedure:

  1. Obtain the metadata URL for the appropriate environment by going to Tools > Identity Federation Configuration and clicking on the copy button at the end of the Octopus Metadata line. The URL will look like https://client_name.octopus-itsm.com/api. Although that URL cannot be accessed directly, your ADFS server will know how to access the relevant information.
  2. In your ADFS server, add a new relaying party trust.
  3. In the Select Data Source step, copy the metadata URL in the prompt for Federation Metadata Address, then click Next.
  4. In the Specify Display Name step, use a name descriptive enough (for example, https://client_name.octopus-itsm.com), then click Next.
  5. In the Configure Multi-factor Authentication step, choose to skip multi-factor authentication, then click Next.
  6. In the Issuance Authorization Rules step, choose to permit all users access to this relying party, then click Next.
  7. In the revision step, make sure only one identifier is used, that encryption is not configured, that claims are present in the list (Name, Given name, Surname, E-mail address), and that the unique endpoint uses WS-Federation passive, then complete the assistant.
  8. From the contextual menu for the relying party configured, edit the claim rules to add a rule.
  9. Choose to send claims using a custom rule and specify the following rule :
c:[
  Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
  Issuer == "AD AUTHORITY"
  ]
=> issue(
  store = "Active Directory",
  types = (
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    "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"
    ),
  query = ";sAMAccountName,mail,givenName,sn;{0}",
  param = c.Value
);

 

Configuring Azure Active Directory

Generally, the integration for Octopus in Azure AD must fulfill the following criterias:

  • You must add an enterprise application registration for each environment that you want to activate Enterprise application is available under the Azure Active Directory blade.
  • Users that want access to the application must have the following:
    • Have an Azure AD Premium license.
    • Be added to the list of allowed users.

Configuring Single sign-on

To configure Single Sign-on, use the following procedure once the enterprise application record has been created:

  1. Click on the 2 - Set up single sign on button.
  2. Choose the SAML authentication mode.
  3. Use the following information to enter Basic SAML Configuration, then press save:
    Identifier [https://client_name.octopus-itsm.com].
    Reply URL [https://client_name.octopus-itsm.com].
    Sign on URL [https://client_name.octopus-itsm.com/web/login.aspx].
    Relay State leave empty.
    Logout Url leave empty.
     
  4. Adjust user attributes and claims according to your environment. Take special consideration to the name claim, which is the primary key used to identify your users.  The content of the name claim must be the same as the content of the Windows username field in Octopus.
  5. Take a copy of the App federation metadata URL located in the SAML Signing Certificat section. It normally has the following format: [https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/federationmetadata/2007-06/federationmetadata.xml?appid=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy].
  6. Provide that URL to start the compatibility verification
     

 

Verifying compatibility

Before verifying compatibility, make sure all instances of your default browser are closed.

Once the verification is started, Octopus will attempt to validate compatibility with your authentication server. The verification will have the following behaviour:

  • WinUI: no apparent behaviour, as this attempt is made in the background.
  • Web Portal: the Web Portal and Web Tech will be launched in a new browser window. You could have to manually login. A message will confirm if it's working.
  • Octopus Web: the Octopus 5 application will be launched in a new browser window. You could have to manually login. A message will confirm if it's working.
Visual Explanation

Activating Identity Federation for End Users (Web Portal)

When you are ready to switch over to centralized authentication for users, select Federated Identity in the appropriate box and click on OK. This change will have the following impact:

  • Your application will restart.
  • Authentication mode changes will apply to all teams. Make sure you have performed all relevant tests to prevent users from being unable to access.
  • As this operation will expire all current authentication tokens, users actually connected to the Web Portal will have to sign-in again.
  • At any time, come back to this option dialog to go back to the previous authentication mode, for which all parameters have been saved.

Activating Identity Federation for Assignees (WinUI, WebTech, Octopus 5)

When you are ready to switch over to centralized authentication for assignees, select Federated Identity from the appropriate box and click OK. This change will have the following impact:

  • Your application will restart.
  • Authentication mode changes will apply to all teams. Make sure you have performed all relevant tests to prevent assignees from being unable to access.
  • As this operation will expire all current authentication tokens, assignees could have to restart their application.
  • At any time, come back to this option dialog box to go back to the native authentication mode.

FAQ Related to Setting Up Identity Federation

If my Federated Identity service is unavailable, how can I connect to Octopus?

In case of an Identity Federation manager outage:

  • No user will be able to access any application while the manager is unavailable.
  • Only assignees able to modify Identity Federation parameters will be able to login. To access the application, they will have to hold the shift key to be prompted for the old authentication using username and password. They will then be able to revert to the previous authentication mode.

If needed, the Octopus Service Desk can help you reset an administrator's password to access back the application in case it was forgotten.

How can I activate OAuthClient on my ADFS server?

From a PowerShell command prompt, enter the following command and replace "mysite" with all the site names that could be invoked in your environment:

Add-AdfsClient -Name "octopus-itsm.com" -ClientId "octopus-itsm.com" -RedirectUri @("https://mysite.octopus-itsm.com/", "https://mysite.octopus-itsm.com/octopus/", "https://app.octopus-itsm.com/mysite/", "https://app.octopus-itsm.com/mysite/octopus/", "https://app1.octopus-itsm.com/mysite/", "https://app1.octopus-itsm.com/mysite/octopus/", "https://app2.octopus-itsm.com/mysite/", "https://app2.octopus-itsm.com/mysite/octopus/", "https://app3.octopus-itsm.com/mysite/", "https://app3.octopus-itsm.com/mysite/octopus/"  )

Enable-AdfsEndpoint -TargetAddress "/adfs/oauth2/"
  • Make sure your site name is all lowercase.
  • Make sure you include the trailing slash in each Redirect URI.
  • Some ADFS server versions might require permission to be granted using cmdlet Grant-AdfsApplicationPermission.

Can Octopus work with other identity providers supporting the WS-Federation Standard?

While theoretically, other providers compliant to the standard could work, none of them have been tested. Actually, the combination of functioning and tested product is to make Octopus work with ADFS 3.0 behind an ADFS 3.0 Proxy or an Azure Active Directory.

If you have another conform system which is not yet supported, you can still try and use the verify function to see if Octopus is able to use the system to authenticate.

How to allow auto-logging for Chrome and Firefox?

By default, ADFS 3.0 does not allow Kerberos/NTLM auto-logging for all browsers. Therefore even if the user is inside the corporate network he is redirected to a login page instead of benefiting from true auto-logging.

Here are useful links to help you understand and resolve this issue:
- ADFS v3 on Server 2012 R2 – Allow Chrome to automatically sign-in internally
- Configuring intranet forms-based authentication for devices that do not support WIA 

Which icon can I use to publish Octopus on the Office 365 Portal ?

Use the following image to publish Octopus on your Office 365 Portal

Visual Explanation

How can I troubleshoot the unique authentication when it does not work ?

The same way that you would troubleshoot most of the other secured services that you offer on the Internet:

  • From a global point of view, make sure that the DNS correctly resolves your proxy server.
  • That your firewall authorizes secured communications to your proxy server.
  • That your proxy server receives connection attempts from your customers/users.
  • That the ADFS service works properly on your proxy server.

Our team does not have the expertise to deploy a federation service.  Can you supply a provider name that could help us in reaching our goal ?

Unfortunately, Octopus cannot recommend any provider at the moment.

X
Help us improve our articles








Help us improve our articles