Setting up SSO with Azure Active Directory

Introduction

Apteco offers single sign-on (SSO) with a few different providers, and this article takes an administrator through the process of getting it set up to use with Azure Active Directory (AD).

Create your Azure account

Signup for a free account at azure.microsoft.com/en-gb/free/

Once you have created and verified your Azure account, you can then create an app.

Create an app within the Azure Portal

To create your app:

  1. Login to portal.azure.com using the account created.

  2. Navigate to the Azure Active Directory service.

  3. Click Enterprise applications from the Manage menu on the left hand side.

  4. Click New Application, then click Create your own application.

  5. Give your application a name and select the option to integrate any other application you don’t find in the gallery (Non-gallery). Click Create.

  6. Wait a short while for the application to be created.

You can configure this SSO provider to use OpenID Connect.

This is a much simpler configuration than SAML as it does not require installation of an Orbit login service. See the article Setting up SSO with OpenID Connect for more information. To instead use SAML, follow the steps below.

Configure SAML for the app

To begin SAML configuration:

  1. Go to the list of applications. You should see the application you have created.

    Click on the name of the application.

  2. Click Set up single sign on, then SAML to open the Set up Single Sign-On with SAML page.

  3. Edit the Basic SAML Configuration.

    You must configure the following fields:

    Configuration Item Value
    Identifier (Entity ID) https://AptecoLoginAPI/
    Reply URL (Assertion Consumer Service URL) https://<yourWebsite>/OrbitAPI/ExternalLogin/AssertionConsumerService/
    Sign on URL https://<yourWebsite>/OrbitAPI/ExternalLogin/AssertionConsumerService/
    Relay State (Optional) https://<yourWebsite>/Orbit/external-login/
    Logout URL (Optional)  

  4. Click Save.

  5. From the section 3 SAML Certificates, Download the Certificate (Base64).

    This will be named as ApplicationName.cer, but you may choose to name it e.g. Azure.cer

  6. From the section 4 Set up <your application name> copy the

    • Login URL: https://login.microsoftonline.com/<Azure GUID>/saml2

    • Azure AD Identifier: https://sts.windows.net/<Azure GUID>

    • Logout URL: https://login.microsoftonline.com/<Azure GUID>/saml2

    You must insert your GUID from Azure config in the URLs above.

Orbit configuration

How to configure Orbit to use a Login Service.

See Orbit login service.

Configure Orbit Login Service

  1. Move downloaded certificate to the certificates folder C:\Program Files (x86)\Apteco\OrbitLoginService\Certificates\Azure.cer

  2. Configure OrbitLoginService appSettings.json (C:\Program Files (x86)\Apteco\OrbitLoginService\appSettings.json)

Where the <> tags are, the settings need to be updated.

Copy 
{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Debug",
        "System": "Debug",
        "ComponentSpace.Saml2": "Debug"
      }
    },
    "WriteTo": [
      {
        "Name": "Trace"
      },
      {
        "Name": "RollingFile",
        "Args": {
          "pathFormat": "C:\\temp\\Orbit\\Logs\\OrbitLogin-{Date}.txt"
        }
      }
    ],
    "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ]
  },
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5005"
      }
    }
  },
  "AllowedHosts": "*",
  "SAML": {
    "$schema": "https://www.componentspace.com/schemas/saml-config-schema-v1.0.json",
    "Configurations": [
      {
        "LocalServiceProviderConfiguration": {
          "Name": "https://AptecoLoginApi/",
          "Description": "Apteco Orbit Login API",
          "AssertionConsumerServiceUrl": "https://example.com/OrbitAPI/ExternalLogin/AssertionConsumerService",
          "SingleLogoutServiceUrl": "https://example.com/OrbitAPI/ExternalLogin/SingleLogoutService",
          "LocalCertificates": [
            {
              "FileName": "certificates/sp.pfx",
              "Password": "password"
            }
          ]
        },
        "PartnerIdentityProviderConfigurations": [
          {
            "Name": "https://sts.windows.net/<GUID>/",
            "Description": "Azure",
            "SignAuthnRequest": true,
            "SignLogoutRequest": true,
            "SignLogoutResponse": true,
            "SingleSignOnServiceUrl": "https://login.microsoftonline.com/<GUID>/saml2",
            "SingleLogoutServiceUrl": "https://login.microsoftonline.com/<GUID>/saml2",
            "PartnerCertificates": [
              {
                "FileName": "certificates/Azure.cer"
              }
            ]
          }
        ]
      }
    ]
  },
  "PartnerName": "https://sts.windows.net/<GUID>/",
  "JWT": {
    "Key": "VerySecretSecurityJWTKey",
    "Issuer": "https://AptecoLoginApi/"
  },
  "AllowedReturnUrlOrigins": "https://example.com/"

Substitute instances of https://example.com with your own website address.

Substitute instances of <GUID> with your actual Azure GUID.

The following parameters will be unique to your Azure instance

appSettings.json parameter name Azure source name
Name Azure AD Identifier
SingleSignOnServiceUrl Sign on URL
SingleLogoutServiceUrl Sign on URL
PartnerCertificates Filename filename of the certificate e.g. certificates/Azure.cer
AllowedReturnUrlOrigins Name of the website e.g. https://<yourWebsite>/

Add users

Add users to the Azure application with the email address used with the Apteco system.

  1. In Azure AD, click +Add > User.

  2. Choose to Create user or Invite user (whichever is appropriate for your system), and enter their details, including email address.

    If inviting a user, then they will receive an email from invites@microsoft.com and they will have to click on the link to connect with the new application.

Assign users to the app

To assign users to the app:

  1. From the Enterprise applications, choose the application that you have created.

  2. Click Assign users and groups.

  3. Click +Add user/group.

  4. Choose Users - None Selected to open the Users panel and select the user that is to be added to the application, then click Select.

  5. Click Assign.

    The user has now been added to the application.

Troubleshooting

Logging in causes “No DataView Error”

When logging in as a user, Orbit gives the following error:

This is caused by Azure passing the User.userprincipalname rather than the users email.

  1. Login to portal.azure.com

  2. Click Azure Active Directory > Enterprise Applications > Your Application.

  3. Click Set up single sign on.

  4. In Attributes & Claims, click Edit.

  5. The Claim name by default is set to user.userprincipalname, click on it to edit it.

  6. Change Source Attribute to user.mail.

  7. Click Save.

    When the user refreshes their browser, they will be able to sign in.

You must now Configure Apteco to use SSO to complete the setup process.