SAML ADFS
Overview
This article provides instructions for configuring AppsAnywhere and ADFS for SAML authentication.
The example shown below includes the configuration required within both AppsAnywhere and ADFS. Server 2016 and ADFS v4.0 is used as the SAML provider.
Before following this article, please read and follow SAML 2.0 Common.
AppsAnywhere configuration
Add a new SSO method using the + Add New Method button at the top of the Single Sign-On Settings page within the AppsAnywhere Admin section.
Select SAML 2.0 and the SAML ADFS option then click Add.
Once the ADFS SAML authentication method has been added it requires configuring. At the top of the SAML 2.0 authentication entry the following fields and options must be selected or populated :-
The Enabled? option must be selected in order to enable this new authentication mechanism.
The Show on Login Page? option can be enabled to ensure this authentication option is presented and available on the AppsAnywhere login dialog.
The Friendly Name option is the text label of the button displayed on the AppsAnywhere login page (if the Show on Login Page? options is enabled).
The URL Identifier option represents the unique URL part used for this authentication method, for example https://my.appsanywhere.com/sso/saml2/<URL Identifier> e.g. https://my.appsanywhere.com/sso/saml2/adfssaml
Each SSO method is designed to have its own unique URL. The values defined in the URL Identifier field must not includes spaces and made up of alphanumeric characters only.
The LDAP Connection(s) to authorize against list allows the selection of the available LDAP connection(s) which will be used to lookup the user's group membership to evaluate the defined provision(s).
If you wish to use SAML only, ensure that no LDAP connections are selected.
The Icon list allows the selection of the icon for the button displayed on the AppsAnywhere login page.
The Expected Username Format field allows for the definition of the expected username format that AppsAnywhere will receive.
Due to the variety of formats the user's credentials may be returned in, you can control what is expected so that AppsAnywhere can handle each and every one.
Such a format can be created by combining up to three "substitution" values, each denoting a different bit of information, with additional literal characters.
The three most common formats are:
{%user%} e.g. alice123
{%short%}\\{%user%} e.g. DOMAIN\alice123
{%user%}@{%domain%} e.g. alice123@domain.com
If no expected username format is provided, the following format is assumed by default {%user%}. See Single Sign-On Settings | Username-and-Format-Examples for more details.
Under the Service Provider section the following fields need to be populated :-
The Entity ID value contains the AppsAnywhere base URL. This will be populated automatically and does not require modifications unless the default base URL is incorrect.
The Certificate (X.509) field requires a valid X.509 certificate in base64 format. The certificate should be associated with the private key defined in the next step. The certificate is presented in the exported provider metadata as the certificate (with the private key) used by AppsAnywhere to sign SAML AuthnRequests sent to the identity provider (ADFS).
This should begin and end with the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, respectively.
The Upload Private Key button allow for the upload of the private key associated with the certificate specified in the previous step.
The private key file must be in base64 format. The private key file should begin and end with the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, respectively.
The Private Key Requirements list allows a pass phrase to be specified if required by the private key.
The Signature Algorithm list allows for the selection of the required encryption level used by AppsAnywhere to encrypt the SAML assertion and response. The defined encryption level must be supported by the identity provider (ADFS). Currently AppsAnywhere only supports RSA SHA-1 or later.
The Digest Algorithm list allows for the selection of the required algorithm used to produce the hash of the message contents, and used by the receiving side to verify the integrity of the sent data. The defined encryption level must be supported by the identity provider (ADFS). Currently AppsAnywhere only supports RSA SHA-1 or later.
In order to determine the Signature Algorithm and Digest Algorithm level required/supported by the identity provider (ADFS), review the token-decrypting and token-signing certificates used by the identity provider (ADFS).
The ADFS Management console will show the current token-decrypting and token-signing certificates in use. Select the relevant entry, right-click and View Certificate. The Details tab on the certificate dialog will display the supported Signature algorithm and Signature hash algorithm. E.g :-
Import IDP metadata
Under the Identity Provider section there are several fields that require populating, however these can be automatically populated by importing the identity provider (ADFS) metadata.
To download the ADFS metadata browse to the following page :-
https://<My ADFS Server>/federationmetadata/2007-06/federationmetadata.xml
It is recommend that Microsoft Edge, Chrome or Firefox browsers are used to download the metadata.xml Other browsers may display the file contents rather than download the XML file.
Paste the metadata information to the Importing MetaData field :-
Click the Add MetaData to form to populate the required Identity Provider values :-
There are additional mandatory fields that are required but not populated by the imported metadata.
See the sections below depending on the required configuration for further information:
The only remaining mandatory field that requires populating is the Username Attribute Name field. This field references the SAML attribute that is returned in the response that contains the user's username value. The field must be populate with the exact attribute name that AppsAnywhere will search for.
The attributes contained within the response are defined within the ADFS claim issuance policy associated with the replying party trust that is created. Details regarding this are provided in the later ADFS configuration section. Please ensure you review the correct section based on your intended configuration, in this case LDAP Only.
The most common values used will be the Name (unique name), UPN (user-principal-name) and/or Windows account name claim type. For these claim types the correct Username Attribute Name value would be :-
Name :-
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
UPN :-
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
If the UPN value is used make sure that the Expected Username Format field referenced earlier in the configuration has the correct value, e.g. {%user%}@{%domain%}.
Windows account name :-
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
If the Windows account name value is used make sure that the Expected Username Format field referenced earlier in the configuration has the correct value, e.g. {%short%}\\{%user%}.
The remaining optional fields which may require the relevant values are :-
The Domain Attribute Name field allows for the definition of the SAML response attribute containing the domain name. This value and SAML attribute is used by AppsAnywhere to determine which domain the authenticating user is a member of.
If multiple LDAP connections have been selected, the Domain Attribute Name may be required if the below are true
The username provided has no domain or short domain name suffix or prefix.
The domain provided in the username is a federated alias (see the Federated Domain Alias option and description below).
When using ADFS, the Domain Attribute Name value is not required as the Windows Account Name claim type can be used to pass through the domain and username in <DOMAIN>\<USERNAME> format.
The Federated Domain Alias field allows for a valid domain name that corresponds to the federated alias used in the user's usernames, e.g. myalias.com. In the event of user authenticate using a federated domain alias (i.e. the domain name portion of the login does not have a represented domain within the infrastructure) and only a single LDAP connection has been selected, a value for this field will be required in order for AppsAnywhere to determine that this part of their login is not a real domain.
Federated Domain Alias is not required or used when more than one LDAP connection is selected; Domain Attribute Name should be specified instead.
If only one LDAP connection is selected and the Active Directory domain uses or has alternative domain suffixes, these additional suffixes must be specificed in the Federated Domain Alias field.
This section only applies if you are using AppsAnywhere v2.12 or later and have the SAML update applied.
When using SAML only, additional fields and values are required in order for the system to obtain the necessary information from the SAML response. The fields must be populate with the exact attribute name that AppsAnywhere will search for. These fields can be found under the Attribute mapping section.
The attributes contained within the response are defined within the ADFS claim issuance policy associated with the replying party trust that is created. Details regarding this are provided in the later ADFS configuration section. Please ensure you review the correct section based on your intended configuration, in this case SAML Only.
The Username Attribute Name field references the SAML attribute that is returned in the response that contains the user's username value.
The most common values used will be the Name (unique name), UPN (user-principal-name) and/or Windows account name claim type. For these claim types the correct Username Attribute Name value would be :-
Name :-
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
UPN :-
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
If the UPN value is used make sure that the Expected Username Format field referenced earlier in the configuration has the correct value, e.g. {%user%}@{%domain%}.
Windows account name :-
http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
If the Windows account name value is used make sure that the Expected Username Format field referenced earlier in the configuration has the correct value, e.g. {%short%}\\{%user%}.
The User Principal Name attribute field references the SAML attribute that is returned in the response and contains the user’s UPN (user principal name) value. The default UPN (user-principal-name LDAP attribute) claim type is:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
The User Display Name attribute field references the SAML attribute that is returned in the response and contains the user’s display name value. The default Given Name (Display-Name LDAP attribute) claim type is:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
The User Unique ID Attribute field references the SAML attribute that is returned in the response and contains the user’s Immutable ID. In this case the user’s primary SID is used. The default Primary SID claim type is:
http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid
The Encoding drop-down field references the required encoding type (if any) which the User Unique ID attribute value uses. The default Encoding value is None and should be used in most cases.
The Domain Attribute field references the SAML attribute that is returned in the response and contains the fully qualified domain name the user is a member of.
In cases were it is not possible to return the FQDN as a stand alone value, an arbitrary value can be defined. In this case the system will fall back to use the domain suffix of the user’s UPN value.
In this example, as we wish the system to use the domain suffix of the user’s UPN value, we enter an arbitrary value of:
mydomain
The Short Domain Attribute field references the SAML attribute that is returned in the response and contains the short (NetBIOS) domain name the user is a member of.
In the cases were it is not possible to return the NetBIOS domain name as a stand alone value, an arbitrary value can be defined. In this case the system will fall back and use the value defined with the Short Domain Fallback Value field.
In this example we define an arbitrary value of:
myshortdomain
The Short Domain Fallback Value field contains the short domain name value you wish to use as a fall back in the cases were the value cannot be retrieved from an attribute in the response.
In this example we define our Active Directory short NetBIOS domain name of:
AD
As mentioned at the start of this section, the attribute values used in this example are detailed in the ADFS configuration section later in this document. If any of these claim/attributes are changed or alternatives are used, the fields must be updated to include the relevant/correct attribute names.
Once the relevant fields have been populated click Save to add the authentication method.
Export Metadata
Once the authentication method has been saved the Exporting MetaData section becomes available at the bottom of the page.
This metadata is used to generate the replying party trust within ADFS. Copy the generated XML data into a text editor (notepad for example) and save as a .xml file.
ADFS configuration
Once the initial AppsAnywhere authentication method configuration is complete, a Replying Party Trust must be created within ADFS. The exported metadata generate by AppsAnywhere can be used to create this.
Using the AD FS Management tool, right-click the Replying Party Trusts entry and select Add Replying Party Trust.
Select the Claims aware option and click Start.
Select the Import data about the replying party from a file option and browse to the metadata xml file previously created.
Click Next to continue.
Specify a Display Name for the Replying Party Trust and any additional Notes if required. Click Next to continue.
Select the required access control policy and click Next to continue.
Note. In this example the Permit everyone access control policy is selected/used.
The information required to generate the replying party trust is automatically populated from the metadata xml. No additional changes are required. Click Next to continue.
Ensure the Configure claims issurance policy for this application is selected and click Close to continue.
Within the Edit Claim Insurance Policy for <Replying Party Trust Name> dialog click the Add Rule button.
See the sections below depending on the required configuration for further information:
If only one LDAP connection has been selected previously within the AppsAnywhere authentication method configuration then it is recommend that the Name and/or UPN SAML attributes are used.
If this is the case select the Send LDAP attributes as Claims from the Claim rule template list and click Next.
Specify a name for the claim rule within the Claim rule name field. Select Active Directory from the Attribute store list.
In the Mapping of LDAP attributes to outgoing claim types section select the SAM-Account-Name and/or User-Principal-Name value(s) from the LDAP Attributes (select or type to add more) column. In the Outgoing Claim Type (Select or type to add more) column next to the select Name for the SAM-Account-Name row and/or UPN for the User-Principal-Name row.
E.g:-
Click Finish to add the claim rule.
If multiple LDAP connections have been selected previously within the AppsAnywhere authentication method configuration then it is recommend that the Windows Account Name attribute is used. This claim ensures the domain name is included with the username in the <DOMAIN>\<Username> format.
In this case within the Edit Claim Insurance Policy for <Replying Party Trust Name> dialog click the Add Rule button.
If this is the case select the Pass Through or Filter an Incoming Claim from the Claim rule template list and click Next.
Specify a name for the claim rule within the Claim rule name field.
Select Windows Account Name from the Incoming claim type list.
Ensure the Pass through all claim values option is selected.
Click Finish to add the claim rule.
Multiple claim rules can be created to pass through as many SAML attributes as required. Within the AppsAnywhere authentication method, simply specify the attribute name required for use.
E.g.
Click OK once the required claim rules have been added to complete the configuration.
This section only applies if you are using AppsAnywhere v2.12 or later and have the SAML update applied.
Select the Send LDAP attributes as Claims from the Claim rule template list and click Next.
Specify a name for the claim rule within the Claim rule name field. Select Active Directory from the Attribute store list.
In the Mapping of LDAP attributes to outgoing claim types section select the SAM-Account-Name, User-Principal-Name and Display-Name value(s) from the LDAP Attributes (select or type to add more) column.
In the Outgoing Claim Type (Select or type to add more) column, select Name for the SAM-Account-Name row, UPN for the User-Principal-Name row and Given Name for the Display-Name row.
E.g:-
In addition, you may which to pass a list of groups the user is a member of. This would allow you to use the groups attribute to map roles within AppsAnywhere, see Creating SAML Attribute Mappings for more information.
This is not required but if you wish to add this, in the Mapping of LDAP attributes to outgoing claim types section select the Is-Member-Of-DL value from the LDAP Attributes (select or type to add more) column.
In the Outgoing Claim Type (Select or type to add more) column, select Group for the Is-Member-Of-DL row.
E.g:-
Click Finish to add the claim rule.
On the Edit Claim Insurance Policy for <Replying Party Trust Name> dialog click the Add Rule button.
If this is the case select the Pass Through or Filter an Incoming Claim from the Claim rule template list and click Next.
Specify a name for the claim rule within the Claim rule name field.
Select Primary SID from the Incoming claim type list.
Ensure the Pass through all claim values option is selected.
Click Finish to add the claim rule.
Click OK once the required claim rules have been added to complete the configuration.
The claim rules created above reference attributes that were used in the previous section during the AppsAnywhere configuration. If any of these claim rules and values are changed or alternatives are used, the previous Attribute mapping fields in AppsAnywhere must be changed to reflect the attributes used.
When configuring SAML ADFS, the following PowerShell Command should be run on the ADFS server to ensure responses are signed correctly as ADFS defaults to assertion only:
Set-ADFSRelyingPartyTrust -TargetName <sp_name> -SamlResponseSignature "MessageAndAssertion"
The value <sp_name> should be set to the name of the relying party trust object configured in ADFS. More details can be found on https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/certificate-signing-options .If the identity provider exposes multiple certificates, you should confirm that the one selected by AppsAnywhere is correct for signing.