Introduction

As part of this guide, you will be taken through step-by-step to setup Keycloak for your Management SUITE. Naming of realm, clients and roles within clients need to be exactly as they appear in this document otherwise it will cause issues when attempting to access Config, Control and Analyze. 

This is available on Synergy SKY Management SUITE 3.0 (31.00.4110 onwards)

To begin please get in touch with us by creating a ticket and we will provide instructions how to start Keycloak.

Initial Setup and Testing

1. Select Synergy CONFIG from Synergy SKY homepage
2. Confirm IP or FQDN ‘External Address’ has been added to Network under General Settings and click on the Save Changes button at the top of the screen
   
   
   
3. If you have not reached out to us via ticket, please do so now as you will not be able to proceed.
4. Reload the Synergy SKY homepage and there should now be a Keycloak icon to be clicked on
   1. Please wait at least 2 minutes before clicking for Keycloak to be fully enabled, otherwise webpage will not load
5.  Create a local Username and Password account and then login with those details to the Administration Console
   
   
   
   
6. Move the cursor over the drop down that says Master and click on Add Realm
   
   
   
7. Name the Realm SynergySKY and click on Create button
   
   
   
8. Select Clients from the left hand panel and click Create button, three (3) will need to be created in total
   
   
   
9. Create Client SynergySKYConfig
   1. Use SynergySKYConfig as Client ID and enter a valid Redirect URL for Synergy SKY appliance (E.g. https://<skyserver>/config) and press Save
      
      
      
   2. Scroll down the page and delete the Root URL information
   3. Valid Redirect URIs should have ‘/config/*’ at the end
   4. Add Base URL & Admin URL with ‘/config/’ at the end
   5. Remove URL from Web Origins and add a ‘+’ symbol to this field
   6. Configuration should look as below image and then click Save at the bottom of the page
      
      
      
10. Select the Roles tab and click on the Add Role button
    
    
    
11. Create a Role Name ‘ConfigAdmin’, add a description and then click Save
    
    
    
    
12. Create Client SynergySKYControl
    1. Use the same steps as for SynergySKYConfig above, changing Client ID to SynergySKYControl and all URL’s to ‘/control/’ then Save
       
    2. Select the Roles tab and click on the Add Role button
    3. Create a Role Name ‘ControlAdmin’, add a description and then click Save
13. Create Client SynergySKYAnalyze
14. Create a client for SynergySKYAnalyze in the same manner as per step 12)
    1. On the settings page, locate Access Type and change from ‘public’ to ‘confidential’
       
       
       
    2. Procced to use the same steps as for SynergySKYConfig above, changing all URL’s to ‘/analyze/’ and Web Origins to *, then Save
    3. Select the Roles tab and click on the Add Role button
    4. Create three (3) Roles ‘Admin’, ‘Editor’ & ‘Viewer’ adding a description and then click Save
       
       
       
    5. Select Mappers and click Add Builtin button
       
    6. Search for Client Roles, tick Add and click Add selected
       
       
       
    7. Click Client Roles to edit
    8. We want to set Client ID to SynergySKYAnalyze, change Token Claim to Role, toggle on Add to ID token and Add to userinfo. Click Save.
       
       
       
    9. Once all have been completed, Clients page should look similar to the below
15. Select Users from left hand panel and click Add User
    
    
    
16. Create a local user (E.g. demo@test.com) then click Save
    
    
    
17. Under the Credentials tab type a password (E.g. password), toggle Temporary to OFF and Set Password
    
    
    
18. Under the Role Mappings tab use the Client Roles drop down to select ‘SynergySKYConfig’ and add ‘ConfigAdmin’ to Assigned Roles
    
    
    
19. Add Roles from ‘SynergySKYControl’ & ‘SynergySKYAnalyze’ in the same manner
    1. You can assign all Analyze Roles to a single User or only one (1)
       N.B. It is possibly to assign roles by default under the Groups heading in the left-hand panel. Here you can create a group, assign Client Roles and then add to Default Groups
       
       
       
       
       
20. Open the Synergy SKY Config Tool page and select Authentication under the General Settings heading
    
21. Toggle the switch to ON and confirm that the Realm and Client names created previously match what’s shown below
    
    
    
22. To get the Analyze Client Secret, go back to the Keycloak configuration page and select the SynergySKYAnalyze client that was created in step 14
23. Select the Credentials tab and copy the Secret from this page to the Analyze Client Secret in the Config Tool
    
    
    
24. To get the Public Key, go back to the Keycloak configuration page and select Realm Settings
25. Select the Keys tab and then click on the Public Key button across from RS256/RSA and copy text from the popup and paste into the Config Tool
    
    
    
    
26. Once Analyze Client Secret and Public Key have been added, click on Verify Keycloak Login button and Sign In with the User (E.g. demo@test.com) account
    
    
    
    
27. Once verified, click on Save Changes in the Config Tool and then deploy the configuration
28. Open a new web browser and try to access Synergy SKY Config Tool page using the User created in Keycloak

Adding AD as Identity Provider

1. In the Keycloak config page, select Identity Providers from left hand panel and choose OpenID Connect v1.0
   
   
2. Give an Alias name (E.g. azuread)
3. Give a Display Name (E.g. Azure AD)
4. Copy Redirect URI information for use in Synergy SKY Management SUITE
   

Register Application in Azure AD

1. Go to aad.portal.azure.com and log in
2. Select App Registrations and then click New Registration
   
   
   
3. Give application a Name (E.g. Keycloak Demo)
   
4. Select the Supported account types (E.g. Single Tenant)
   
5. Select Web for Redirect URI and paste link copied from Keycloak configuration page
   
6. Click on Register
   
   
   
7. Click on Endpoints on next screen and copy the OAuth 2.0 authorization endpoint (v2) and OAuth 2.0 token endpoint (v2) to the associated fields in Keycloak
   
   
   
   
8. Close the Endpoints window and copy the Application (client) ID to the Client ID section of Keycloak, setting the Client Authentication method to Client secret sent as post
   
   
9. A Client Secret is now required.
10. In Azure AD, select Certificates & secrets and then click New client secret
    
    
11. Add a Description (E.g. Keycloak Secret) and set the Expires timeframe (N.B. make a note of this if needing to renew at a future time) then click on Add
    
    
12. Copy the Value of the secret once done
    
    
13. Paste the secret into the Client Secret section in Keycloak configuration and add some Default Scopes (E.g. openid profile email) and then click on Save at the bottom of the page.
    
    

Try and login to Synergy SKY Config Tool from a new private window or a different web browser. There should now be a button at the bottom saying “Azure AD” or whatever Display Name was specified in step 3. Click on the button and login using AD.