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 use 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).
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 populate :-
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 access the ADFS metadata browse to the following page :-
https://<My ADFS Server>/federationmetadata/2007-06/federationmetadata.xml
E.g.
https://fs.int.local/federationmetadata/2007-06/federationmetadata.xml
The metadata page will look like the following :-
If the metadata page looks like the following :-
When using Internet Explorer the metadata may not be formatted correctly as the URL is not in the browsers local intranet sites list. Add the URL to the local intranets sites list and refresh the page.
Note that the metadata output displayed by Internet Explorer cannot be copied and pasted directly into the AppsAnywhere Import MetaData field as it is not valid XML. The output can be copied into a text editor (notepad for example) and perform a find and replace for the "- " value (without the quotes). There is a trailing space after the "-" (minus sign) which is required to ensure the correct values are replaced. Simply replace this value with nothing (i.e. and empty value).
When using Chrome or Firefox the browse may download the metadata.xml file rather than displaying the contents. If this is the case simply open the downloaded metadata.xml file using a text editor and copy all of the content.
Paste the metadata information to the Importing MetaData field :-
Click the Add MetaData to form to populate the required Identity Provider values :-
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.
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.
When using ADFS this would only be required if one LDAP connection is selected and a federated domain alias is used.
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.
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.
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.