Product versions - {Software AG Cloud: 10.15.0.0.1013 and Azure AD Free.}
Introduction
Setting up SSO in the Software AG Cloud (SAG Cloud) with Azure Active Directory (AAD) as the IDP is a process that requires some setup in both environments. It requires information from both environments, so it makes sense to open two browser windows from the start in order to follow the process.
The documentation related to the topic at hand is scattered across sites (Microsoft and Software AG) and some information is seemingly mentioned only in passing without concrete examples - something that can lead one to misconfigure it and then have to spend time researching and fixing it.
With this short article, I am hoping to condense all relevant information in one location. The links given under the “Useful links| Relevant resources” section contain all the background and further information. This article is meant to provide a cheat sheet but does not replace the official documentation in any way.
The process described here has been tested with the product versions listed above.
Pre-requisites
- You require a SAG Cloud tenant and a user with admin access to the tenant.
- You require access to an Azure Active Directory subscription (free edition will suffice).
Preparation
If the user that you want to use going forward already exists in AAD and have been assigned one or more roles, then you can skip this section.
In my case, I created a new external user, using the “Invite User” template. I assigned only one role (“Reports reader” – one of the built-in roles. Since I use the free version of AAD, I cannot create custom roles) to the user for testing.
For a detailed description, please see Tutorial: Microsoft Entra SSO integration with Software AG Cloud - Microsoft Entra ID | Microsoft Learn
The resulting user created in AAD should look like this:
Setting up SSO in Azure Active Directory
This step requires some information from the next step and vice versa, so ensure you are logged in to both environments.
More details of the steps to be taken can be found at Tutorial: Microsoft Entra SSO integration with Software AG Cloud - Microsoft Entra ID | Microsoft Learn
- Set up a new Enterprise Application in AAD
- For a detailed description of this part, see Tutorial: Microsoft Entra SSO integration with Software AG Cloud - Microsoft Entra ID | Microsoft Learn
- To start, you have to add a new “Enterprise Application” in AAD - the screenshot below shows what it looks like when you have an enterprise application added already
- If you click the “New Application” button, you’ll be taken to the application gallery - since the list is pretty big, you can narrow it down by filtering on “software ag cloud”, as shown below
- Select “Software AG Cloud” from the list, give it a name and click “Create” - the create button is not shown in the picture below, it is down at the bottom of the panel that is brought up
- The link highlighted in the picture above is the one given under “Useful links” for AAD - now you know where to find it in AAD
- Once the application is created in the previous step, you must configure it. The overview panel of the app shows you the configuration steps - in this case really only 2 for a minimal configuration
- Assign users and groups
- In this step, you assign the user(s) and/ or group(s) who require SAML SSO access to the SAG Cloud using AAD as the identity provider.
- Click on the “Assign users and groups” link in the overview and you’ll be taken to the detail page where you can add individual users or groups (note that these users/ groups must already exist in AAD)
- You’ll see that the user is already added in the screenshot above - click on the Add user/ group" button to add users/ groups - if you don’t find them, check whether they have been created already in AAD (look under the “Preparation” heading earlier in the article)
- Set up SSO - this is really the part we’re after, everything up to now just “laid the table”
- For this step, you’ll need information from the SAG Cloud tenant, so make sure that you set up this part in parallel - refer to the next session, “Setting up SSO in Software AG Cloud”
- Click on “Single sign-on” in the left-hand pane of your newly created enterprise application. You’ll notice a numbered list - we are really interested in items 1-3
- The screenshot above shows the detail required to complete item 1. These details all come from the SAG Cloud tenant where you are setting up SAML SSO. The parts that are obscured are the parts related to the specific tenant.
- We have three fields to be completed:
- Identifier
- takes the form: https://<SUBDOMAIN>.softwareag.cloud/auth/realms/TENANT-NAME
- replace the parts in caps above with the values from your actual tenant
- e.g.: https://idm-eu-central-1.softwareag.cloud/auth/realms/testaad (fictitious!)
- Reply URL
- takes the form: https://.softwareag.cloud/auth/realms/TENANT-NAME/broker/IDENTITY-PROVIDER-NAME/endpoint
- again substitute the actual values from your tenant in the caps fields above
- e.g.: https://idm-eu-central-1.softwareag.cloud/auth/realms/testaad/broker/azuread/endpoint
- this assumes the name that you give the identity provider that you’ll create in the next section, is called “azuread”
- Sign on URL
- same as the reply URL above
- Identifier
- Complete “Attributes and claims”
- Leave the defaults, but add a new claim, called “roles”, with the value “user.assignedroles”, as shown in the picture above.
- Make a note of the claim names, you are going to need it when setting up the SAG Cloud part
- SAML Certificates
- Copy the value of “App Federation Metadata Url”, you need this as part of the SAG Cloud setup
- It may be tempting to use the “Test” button in AAD, but without the setup complete, this is unlikely to work
Setting up SSO in Software AG Cloud
OK, this is the other side of the coin that must be completed before we can test the SAML SSO setup.
- Log into the SAG Cloud tenant as an administrative user and go to “Administration”
- Select the “Single sign-on” tab:
- As you can see, I already have an identity provider set up and activated.
- Click on “Add identity provider” and complete the three steps below. These steps all require values from AAD
- Configuration
- Provide a name (this will be shown on the login page)
- Provide a unique ID – this is included in the Software AG Cloud redirect URI, the “IDENTITY-PROVIDER-NAME” in the previous section
- The Single sign-on service URL is taken from Azure, the “App Federation Metadata Url”, as mentioned in the previous section
- If you do NOT provide this value, you have to create “from scratch”. If you provide this value, it is used to populate the values required. My advice is to use this approach when possible. Where not possible, refer to the documentation links for details on how to handle this.
- Attributes
- It is very important this these values are correct, else the SSO will NOT work! I required the following:
- Email - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
- First name - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
- Last name - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
- If you have other attributes used to identify a user, add them here
- Roles
- As you can see, I took the easy way out here and just used the “Assign default Software AG Cloud roles” - if you need to map assigned AAD roles to SAG Cloud roles, please refer to the documentation links for that
- Save and make sure the IDP is activated. You are now ready to test SSO.
- Configuration
Testing SSO from Software AG Cloud
- Open a browser tab and access the SAG Cloud tenant login page.
- Click on “Login”
- You should now be presented with a page where you can either log in using username/ password, or the new SAML SSO IDP that you just created:
- Click on the new SAML SSO link and provide the login credentials - you should be redirected to the Microsoft login
- If everything is correctly configured, you should now be logged in to the SAG Cloud
- From your admin SAG Cloud login, you should now be able to see the new user created in SAG Cloud (remember, we did not create the user in the Cloud tenant, it was created only in AAD)
*
In closing
I hope this article will be useful to someone other than me when setting up SSO using AAD as IDP.
If you run into problems when setting up SSO, check and recheck that the values are correct.
If you encounter an error message “You cannot log in either because the values for the Software AG Cloud attributes and identity provider user attributes don’t match or because one of the fields First Name, Last Name or Email is empty. Contact your Software AG Cloud administrator.”, double-check the values provided for the attributes in the SAG Cloud tenant - if you opted for the short claim names (e.g. “user.surname”), replace it with the fully qualified claim name (e.g. “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname”)
If you changed any of the values picked up from AAD, you may run into errors. When the single sign-on configuration has “Validate signature” set to “On”, a modification of the assertions causes an error: “invalidFederatedIdentityActionMessage”. However, without the “Assertions signed” setting set to “On” the entire signature can be removed from the SAMLResponse that is passed via the browser from IDP to SAG Cloud, allowing a malicious actor to access the tenant as any user/ group.
If the SSO is still unsuccessful, see if you can troubleshoot the individual URL values that were used in setting up SSO from both AAD and SAG Cloud (note that extra information may be required, so look into how to debug SAML-based SSO, see the link below).
Useful links | Relevant resources
This article is based on the contents of the three resources below.
- Software AG Cloud:
- Software AG Cloud tenant documentation:
https://<tenant address>.softwareag.cloud/site/documentation/identity-provider-help.html#/ - Example of Configuring Microsoft Azure to Connect to Software AG Cloud as the SAML Identity Provider
- Software AG Cloud tenant documentation:
- Azure Active Directory: