Step By Step: SSO with SAML for Azure AD

Follow this setup guide to setup SSO with Azure Active Directory using SAML.

1. Log in to the Azure Portal and search for Active Directory

azure_portal_start_screen

2. Start with configuring groups, these will be associated with Hyperglance Roles at a later stage. Select Groups:

select_azure_ad_groups

3. Click New Group and let's call this group Hyperglance Admins.

Refer to our Role-Based Access-Control (RBAC) Documentation to learn about other kinds of user besides admins.

click_new_group

4. Add members to your group by clicking No members selected and then selecting some users:

click_no_members_selectedselect_group_members

5. Click Create:

create_new_group

Repeat the previous steps to create additional groups for other Hyperglance Roles if needed. For the list of Roles supported by Hyperglance please refer to the document describing Role-Based Access-Control (RBAC) used in Hyperglance

 

6. Return to the Azure AD Organisation management and select Enterprise applications:

select_enterprise_applications

7. Click New Application:

click_new_application

8. Select Non-gallery application:

select_non-gallery_application

9. Give the application a name and click Add:

add_enterprise_application

10. From the left side Select Single sign-on and pick the SAML option presented:

select_single_sign-onselect_saml

11. Click to edit User Attributes & Claims:

edit_user_attributes_and_claims

12. Click Add new claim:

click_add_new_claim

13. Name the new claim role (Hyperglance expects that name!) and expand the Claim conditions section:

create_new_claim_role

14. For User type select Any and for Scoped Groups choose the Hyperglance Admin group we created earlier:

create_new_claim_role_select_groups

15. Set the Source to Attribute and type in HyperglanceUser;HyperglanceAdmin as the Value.

Note: There must not be any spaces around the semi colon that separates the Hyperglance role names.

create_new_claim_role_set_attribute_value

If you added any additional groups at the steps 3-5, then add them with additional claim conditions as above and assign them the appropriate set of Hyperglance roles.

 

16. Click Save

create_new_claim_role_save

17. Navigate to Users and groups and click Add user

select_users_and_groupsselect_users_and_groups_add_user

18. Select users and/or groups that you will allow to access the Hyperglance application. Hyperglance will also show in their apps access panel (e.g http://myapps.microsoft.com ).

select_users_and_groups_select_users

When ready click Assign:

select_users_and_groups_assign

19. For the next few steps we must configure the Hyperglance VM. SSH into the VM, edit the file /var/lib/data/hyperglance/config.env and set the SAML_ENABLED flag to true.

 

20. Generate Service Provider (SP) metadata by running this script (make sure to adjust the IP address as appropriate):

mellon_create_metadata.sh https://188.166.207.211 https://188.166.207.211/saml

The 1st parameter: The SAML Entity ID -  This can be any URI that uniquely identifies your Hyperglance install, using the IP address is a good way to do that.

The 2nd parameter: The URL to the SAML endpoint for your Hyperglance VM. Must be set to: https://{yourHyperglanceVM}/saml

The IP address or DNS name you use here must be the one that your browser would use to reach the Hyperglance VM because SAML works using browser redirects!

 

If the script was successful you will see an output like this:

Output files:
Private key: /etc/httpd/mellon/sp.key
Certificate: /etc/httpd/mellon/sp.cert
Metadata: /etc/httpd/mellon/sp.xml
Empty IdP metadata file: /etc/httpd/mellon/idp.xml
Host: 188.166.207.211

Endpoints:
SingleLogoutService: https://188.166.207.211/saml/logout
AssertionConsumerService: https://188.166.207.211/saml/postResponse


The script has generated an sp.xml file and an empty idp.xml we will need to use these in the next steps.

 

21. Replace (or update) the empty idp.xml file with the Federation Metadata XML you can download from the Sign sign-on page in the Azure portal:

azure_ad_download_idp.xml

Make sure you name the file idp.xml and place it at /etc/httpd/mellon/idp.xml

 

22. Restart the services running on the VM for our changes to take effect:

sudo docker-compose -f /etc/docker-compose.yml up -d

 

23. Download the sp.xml file generated in step 20 to your local machine and then upload it to Azure by clicking Upload metadata file:

click_upload_metadata_fileupload_medatadata_file

24. After the upload no other changes are needed so just click Save and close the form:

save_basic_saml_configurationclose_basic_saml_configuration

25. Azure will now suggest you test your new SSO configuration. Try it, it should now work!

During your first visit to Hyperglance you may be prompted by your browser to acknowledge that Hyperglance (by default) ships with a self-signed SSL/TLS certificate.

If this happens accept the warning by clicking Advanced and then Proceed (Note different browsers may show this differently):

hyperglance_self-signed_cert_error_ec2hyperglance_self-signed_cert_error_proceed_ec2

If you are also asked to resubmit the form data then choose to accept.

 

All being well you should now be logged into Hyperglance!

Congratulations you have now completed the setup.