Setting up SSO with Azure Active Directory

This article takes an administrator through the process of setting up SSO with Azure Active Directory (AD).

Create an app in the Azure portal¶

1. Navigate to the Azure Active Directory service.

   

2. Click Enterprise applications from the Manage menu on the left.

   

3. Click New Application, then Create your own application.

4. Give your application a name and select Integrate any other application you don't find in the gallery (Non-gallery). Click Create.

   

5. Wait for the application to be created.

Configure SAML for the app¶

1. From the list of applications, click on the name of the application you created.

   

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 with the following values (substitute your actual server address for the placeholder):

   Configuration item	Value
   Identifier (Entity ID)	https://AptecoLoginAPI/
   Reply URL (Assertion Consumer Service URL)	https://[your-server]/OrbitAPI/ExternalLogin/AssertionConsumerService/
   Sign on URL	https://[your-server]/OrbitAPI/ExternalLogin/AssertionConsumerService/
   Relay State (Optional)	https://[your-server]/Orbit/external-login/

4. Click Save.

5. From section 3 SAML Certificates, download the Certificate (Base64). You may choose to name it Azure.cer.

6. From section 4 Set up (app), copy the:

   • Login URL: https://login.microsoftonline.com/[GUID]/saml2
   • Azure AD Identifier: https://sts.windows.net/[GUID]/

   Substitute your actual Azure GUID into these URLs.

Configure the Orbit Login Service¶

See Orbit login service to install and configure the Login Service first.

1. Move the downloaded certificate to the certificates folder:

   Text Only

   C:\Program Files (x86)\Apteco\OrbitLoginService\Certificates\Azure.cer
   

2. Edit the Orbit Login Service configuration file with the following JSON:

   JSON

   {
     "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",
             "LocalCertificates": [
               { "FileName": "certificates/sp.pfx", "Password": "password" }
             ]
           },
           "PartnerIdentityProviderConfigurations": [
             {
               "Name": "https://sts.windows.net/<GUID>/",
               "Description": "Azure",
               "SignAuthnRequest": true,
               "SingleSignOnServiceUrl": "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 <GUID> with your actual Azure GUID. The following parameters are unique to your Azure instance:

   Parameter	Azure value
   SingleSignOnServiceUrl	Login URL from Azure
   PartnerCertificates.FileName	Filename of the certificate, e.g. certificates/Azure.cer
   AllowedReturnUrlOrigins	Base URL of the website hosting Orbit

Add users to the Azure application¶

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

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

   

2. Choose Create user or Invite user, and enter the user's details including email address. Invited users receive an email from invites@microsoft.com with a link to connect with the new application.

Assign users to the app¶

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

2. Click Assign users and groups.

   

3. Click +Add user/group.

4. Choose Users—None Selected to open the Users panel, select the user to add, then click Select.

   

5. Click Assign.

Troubleshooting¶

Logging in causes a "no dataview" error¶

When logging in, Orbit displays the following error:

This is caused by Azure passing User.userprincipalname rather than the user's email address.

1. Log in 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. Click on the default claim name (user.userprincipalname) to edit it.

   

6. Change Source Attribute to user.mail and click Save.

   

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