SSO with Azure AD

We need to add the App roles which requires a unique ID from Octopus server.

For e.g : we are creating 2 roles user and Admin. Below is the syntax where in unique guid is required for the specified role in manifest. Let me know where I can find this values.

“id”: “NEWGUID1”,
“allowedMemberTypes”: [“User”],
“description”: “Octopus Administrators”,
“displayName”: “Octopus Admins”,
“isEnabled”: true,
“value”: “octopusAdmins”

          "id": "NEWGUID2",
          "allowedMemberTypes": ["User"],
          "description": "Octopus Testers",
          "displayName": "Octopus Testers",
          "isEnabled": true,
          "value": "octopusTesters"

Hi @aditichalke

Thanks for getting in touch with us regarding Azure AD integration. I can see that you are likely to be following the advice in this article:

You should just be able to generate your own GUID using powershell like this (or any other guid generator you want to use)

C:\> New-Guid


As per the docs, the important value to align with Octopus, is the value property: that must line up with the value you use when adding the external group to the Team in Octopus configuration.

Hope this helps!


Thanks Jim. Is this powershell need to be run from Octopus server. Is this role need to be present on octopus server?

If we do not create this roles , by default I do see a role name “default Access” on azure portal while adding users from Azure AD. I select this role & add AD groups to this role, what type of access they will get.

With the default access role selected from azure portal, can we control users & Admin role access from Octopus management console.

Hi @aditichalke

Hopefully I can answer your questions below.

Is this powershell need to be run from Octopus server.

Generating a GUID can be done from any location, because they are Globally Unique. The example I gave is a standard powershell command. Older versions of powershell may require the use of a different syntax [guid]::NewGuid() which is just a direct call to the method of the underlying .NET type.

Is this role need to be present on octopus server? If we do not create this roles , by default I do see a role name “default Access” on azure portal while adding users from Azure AD.

You definitely need to create a new App Role in Azure.

First, you’ll create a new role in the Azure portal, using the manifest, as you have done, giving it your brand new GUID, and value of octopusTesters (as an example)

Later, you’ll link that AAD Role, to a Team in Octopus, using octopusTesters as the RoleID, here


From the docs:

The value property is the most important one. This value becomes the external Role ID you will use later on when adding this role to a Team in Octopus Deploy.

You only need to all of this, if you want to connect Azure AD with Octopus teams. You can opt not to do this at all, in which case, users will simply authenticate with Azure AD instead and would not be mapped into an Octopus Team automatically.

what type of access they will get.

The permissions they will have inside of Octopus, depends on the team they have been added into. If you have an Octopus Testers team, mapped to an AAD Role called octopusTesters, then any users in that AAD Role will take on the permissions of the Octopus Testers team.

This is controlled via User Roles and adding those to the team.

Hopefully I am helping to clarify, let me know if there is more information I can help you with here.

Kind regards,

Hi Jim,

Thanks for the explanation. However I do not see option Add external group/Role under members section for teams on Octopus console.

As you mentioned I can still go ahead & add users on azure portal with Default access Role, which in term will grant user access to Octopus but Admin has to add the user in team which has local roles added to it to get access to projects assign to those teams.

Hi Jim,

I am going to do SSO activity by tomorrow Friday at 3 PM EST. Do you provide any support if something goes wrong during SSO integration.

Hi there @aditichalke,

Thanks for letting me know you can’t see that option. What version of Octopus Deploy are you running there? That might explain why you don’t see the ‘Add External Role’ button - normally it is on the Team page.


Do you provide any support if something goes wrong during SSO integration.

If you do run into specific issues, reach out to us here or - we try our best to respond within 24 hours.

We don’t have anyone available to be on call for such an event, most of us are based in Australia, for example your Friday 3pm is my 6am on Saturday.

My advice here is to have a rollback plan, and if possible test your scenario in a test environment first. If think you may need faster response times on your support queries you’ll be better suited to do something like this late on your Tuesday or Wednesday, (your 5pm is closer to the start of our day)

We also have a series of partners who know our product really well that can provide consultation services, if you need somebody on site, or on call:

You can also join our community slack channel for help from others in the community around the world and our international staff, hang out there too - though there are no guarantees to support being provided there, but it is worth joining up and getting involved!

Hope this helps,


Hi Jim,

We are version 2.0. I can reschedule it to later hours Tuesday or Wednesday so that I can get the response from you. let me know with this version I can go ahead & do the AAD integration.


Octopus Version : 2018.6.15.0

Question :

  1. After SSO, how users are going to get notified about the logon method. Is this we have to notify users before the activity or there is a automated email goes to users about the SSO logon enablement after we enable this feature in Octopus
  2. If SSO is not working for some reason , can we revert back & disable AAD integration from Configuration ➜ Settings ➜ Azure AD. after disabling this, will user still be able to login with their old username & password.

Hi @aditichalke,

Thanks for letting me know what version you are on, the ‘Add External Role’ button should be present for your version, once you’ve enabled the provider.

To answer your questions, you’ll need to notify users that they can use the login buttons for Active Directory, we don’t do any automatic emails. You should be fine to revert back - the users will not be removed from Octopus Server.

All the best for your SSO integration!

Hi Jim,
I enabled the Azure AD integration. please find the below.

  1. After enabling SSO , I do not see the option to enable external role
  2. URL is not redirecting to SSO page for AD Authentication. I had to choose sign in with Microsoft option which gives me AD sign in page
  3. After login to Octopus by using AD credentials, I lost my Admin privileges as I have got default access with limited access

Please help. I am available now , if you can send me the reply & help me get this working

I am still able to login with regular username & password where I have admin access.
we are using 2 roles -->System Administrator, GEP_Role which I am afraid if we choose AD authentication we loose after login.

Hi Jimmy,
I was able to get my access back as I added external role in manifest.
only concern is the portal is not automatically redirecting to Azure AD page for sign in.
user can still login with local userID & password.

Hi @aditichalke

Good to hear you got back to a working state!

In order to troubleshoot the Azure AD page configuration, could you confirm if your Issuer & ClientID values are set correctly?

Does this URL contain the same GUID as your Azure Active Directory Tenant ID?

For example, if your Azure Active Directory Tenant ID was 5ed4ad8b-65ad-c4fa-09de-5c6f16e5fc78 then the value for Issuer should be: (full instructions here:

If so, are you able to browse to that URL manually?



Hi Jim,
I checked with Azure Support. we cannot browse to URL mentioned in issuer field manually by design. they are asking to check from Octopus side if anything missing.
All settings as per the document are in place. It should auto redirect to Azure AD page from local username/password prompt.

SSO is working but when you click on Sign in Microsoft button.

Hi there @aditichalke

Apologies, I wasn’t aware this was the case that Azure prevents manual browsing to that URL.

In regards to automatically redirecting to that page - have you enabled the --autoLoginEnabled=true setting as per our documentation?

Based on this documentation, it looks like you’ll also need to disable the standard ‘Username / Password’ login feature from the Settings page.

Let me know if this works for you!

All the best,

thanks I will enable the auto login.

  1. How do I add new users
  2. what will happen to old users who has username / password. will they be able to login with azure AD credentials. any notification needs to send them before we do so.

Any update on my question.

Apologies for the delay in our response to you @aditichalke

To answer your first question, you would add users in both Azure AD, and in Octopus, and then link them using the Azure AD external login section on the User in Octopus

image.png1702x812 64.3 KB

By linking existing users in this way, you will ensure your old users can login with their Azure AD credentials.

You may wish to inform your users to start using their Azure AD credentials, this is entirely up to you and your business, Octopus doesn’t get involved in that side of things.

Hope this helps!