Overview

This article will cover the configuration required for AppsAnywhere to use a SAML 2.0 provider for single sign-on.

Please read Single Sign-On Settings before proceeding

Security Assertion Markup Language 2.0 (SAML 2.0) is a version of the SAML standard for exchanging authentication and authorization information between services and providers. It is an XML-based protocol that uses security tokens to pass information about an end user between an identity provider and service provider. These security tokens contain assertions which are formed from multiple attributes holding the information about the end user; AppsAnywhere currently supports only a single assertion, but this assertion may have more than one attribute which are then traversed by name. The attributes that are part of this assertion will then typically contain the identity information required to authenticate the user and authorize them for use of AppsAnywhere.

AppsAnywhere currently supports quick set up for two identity providers:

  • Shibboleth 2

  • Active Directory Federation Services

If an identity provider that supports SAML 2.0 is required and not listed above, use “Custom" setup

It is recommended you ensure set up is complete on the provider side first, so that you have the XML metadata necessary to make configuration of the SSO method within AppsAnywhere much easier.

It is worth noting that AppsAnywhere does not support SAML 1.x or Shibboleth 1.x.

  1. 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 .

  2. If using an alternate SAML provider, please ensure the IDP is configured to sign messages/responses and assertions.

  3. If the identity provider exposes multiple certificates, you should confirm that the one selected by AppsAnywhere is correct for signing.

Adding SAML 2.0 Methods

If you are unfamiliar with the process for adding new SSO methods, steps for doing this and information about common settings associated with all SSO methods can be found on the Single Sign-On Settings page. When selecting which method to add however, be sure to pick from the SAML 2.0 category, and select the one that corresponds to the identity provider you are planning to use.

For Shibboleth 2, select the following:

Or for Active Directory Federation Services, select:

If neither of the above are suitable, select:

SAML 2.0 Specific Settings

In addition to the common settings mentioned on the Single Sign-On Settings page, SAML 2.0 methods include a number of others which can be broken down into two sections: the service provider and the identity provider.Service Provider Settings

These are the settings pertaining to AppsAnywhere as a SAML service provider. You will have relative freedom with the configuration here but you should make sure that the signature and digest algorithms are supported by your identity provider.

Field Name

Description

Intended Value

Entity ID

A globally unique identifier within your SAML environment.

This will typically be a standard well-formed URL (although not limited to), e.g. https://myappsanywhere.com

You should not need to change this from the default unless you are adding multiple SAML 2.0 SSO methods.

Certificate (X.509)

Allows you to provide text representing a X.509 certificate. The certificate should be associated with the private key you plan on using (see below).

This is presented in the exported service provider metadata as the certificate (in conjunction with the key) used by AppsAnywhere to sign SAML AuthnRequests sent to the identity provider.

If you are unsure about certificates, private keys and certificate signing requests, DigitalOcean has a great guide about using OpenSSL to perform related procedures.

A valid X.509 certificate in base64 format.

This should begin and end with the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" lines, respectively, and without double quotes.

Upload Private Key

This allows you to select a file from your local machine which will be used as the private key. This key should be associated with the certificate you plan on using (see above).

AppsAnywhere uses the key in conjunction with the certificate to sign SAML AuthnRequests sent to the identity provider.

If you are unsure about certificates, private keys and certificate signing requests, DigitalOcean has a great guide about using OpenSSL to perform related procedures.

A valid RSA private key in base64 format.

This should begin and end with the "-----BEGIN PRIVATE KEY-----" and "-----END PRIVATE KEY-----" lines, respectively, and without double quotes.

Private Key Requirements

Whether or not the private key is protected by a pass phrase.

This will determine the visibility of the field used to enter the pass phrase, and will also clear any currently set value when the pass phrase is set as not required.

Whether the private key requires a pass phrase is determined during its creation, so if you are unsure if one has been configured, set as not required.

When you attempt to export the service provider XML metadata after completing and saving the configuration, you will receive an error in the event the private key does require a pass phrase.

Private Key Pass Phrase

The pass phrase for the private key. On subsequent edits, this value will be hidden to the user.

Note: this field is hidden in the event it is not required.

The pass phrase either provided to you, or the one set by you during creation of the private key.

Signature Algorithm

The algorithm used to encrypt the SAML assertion and response.

This needs to be an algorithm supported by the identity provider.

RSA SHA-256 is one of the more commonly available methods, so if you are unsure then use this.

RSA SHA-1 should be avoided if at all possible.

Digest Algorithm

The algorithm used to produce the hash of the message contents, and used by the receiving side to verify the integrity of the sent data.

This needs to be an algorithm supported by the identity provider.

SHA-256 is one of the more commonly available methods, so if you are unsure then use this.

SHA-1 should be avoided if at all possible.

Identity Provider Settings

These are the settings pertaining to your identity provider. You will have limited freedom in the configuration of this section as each part will need to reflect how your identity provider is configured.

By far the easiest way to configure the majority of these settings is by using the XML metadata obtained from your identity provider, and importing it into AppsAnywhere.
Feel free to skip to the metadata section below, but note that none of the fields that require SAML attributes or the federated domain aliases are populated.

Field Name

Description

Intended Value

Entity ID

The globally unique identifier within your SAML environment for the identity provider you are planning to connect to.

This will typically be a standard well-formed URL (although not limited to), e.g. https://mysaml2endpoint.com

Authentication Base URL

The base URL of your chosen identity provider, which the Single Sign-On Path is appended to when determining the full URL.

Example: https://mysaml2endpoint.com[path-appended-here]

A standard well-formed URL, ideally with no trailing slash, e.g. https://mysaml2endpoint.com

Single Sign-On Path

The path which will be appended to the Authentication Base URL, forming the complete HTTP redirect binding URL used by AppsAnywhere when performing SAML single sign-on.

Example: https://mysaml2endpoint.com/example

A URL-compliant URI, ideally with no trailing slash (unless only "/"), e.g. /example

Certificate (X.509)

The public X.509 certificate used by the identity provider you are planning to connect to.

AppsAnywhere requires signing of SAML AuthnResponses by the identity provider, so make sure the correct certificate used for signing is provided here.

A valid X.509 certificate in base64 format.

This should begin and end with the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" lines, respectively, and without double quotes.

Username Attribute Name

To determine the identity of the user, the username should be made available to AppsAnywhere within the SAML AuthnResponse returned by the identity provider. The name of this attribute can then be provided here so that during the authorization process AppsAnywhere can extract this information.

This is the username that will be matched against the provided username format.

The SAML-compliant attribute name containing the username in the SAML AuthnResponse, e.g. email

Note: This must be the attribute name and not the friendly name

Domain Attribute Name

In order for AppsAnywhere to know which local domain the authenticating user is a part of, the name of a SAML attribute that provides this information may be required.

If multiple LDAP connections have been selected, there are two main scenarios where this would be the case:

  • The username provided has no domain or short domain name suffix or prefix

  • The domain provided in the username is a federated alias

See below for more information about federated domain aliases.

The SAML-compliant attribute name in the SAML AuthnResponse containing the domain the user is part of, e.g. domain

Note: This must be the attribute name and not the friendly name

Federated Domain Alias

In the event your users authenticate using a federated domain alias (i.e. the domain name portion of their login does not have a represented domain within your infrastructure) and only a single LDAP connection has been selected, a value for this field will be required in order for AppsAnywhere to know that this part of their login is not a real domain.

Note: this field is not required or used when more than one LDAP connection is selected; Domain Attribute Name should be specified instead.

A valid domain name that corresponds to the federated alias used in your user's usernames, e.g. myalias.com

If the domain found in the username matches this set value, then it will be ignored, and the domain associated with the selected (single) LDAP connection will be used instead.

Attribute Mapping Settings

To use SAML attribute mappings, an additional update to your AppsAnywhere servers is required along with Creating SAML Attribute Mappings

These settings control the sources of the attribute values that are required for SAML logins. As SAML can be used in conjunction or without an LDAP connection, there are some quick-start options that will fill out the fields with some basic information that may help in these scenarios.

When using SAML only (without an LDAP connection)

Values automatically populated by the quick-start options are:

Quick-start Option

Fields populated

Value

Description

Hybrid Azure Active Directory

  • I currently use LDAP and wish to only use SAML

Encoding

Base64

The encoding value is changed from None to Base64. This is based on the User Unique ID Attribute value mapped to the user.onpremiseimmutableid property which is Base64 encoded. The user.onpremiseimmutableid returns the users on premise Active Directory Immutable object ID value which AppsAnywhere can use to match previously stored information. This ensures that when transitioning from LDAP to SAML, user profile information amongst other settings are retained.

User Principal Name Attribute

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Default claim added automatically when configuring an AzureAD Enterprise application with SAML Single Sign On.

User Display Name Attribute

http://schemas.microsoft.com/identity/claims/displayname

Default claim used in certain situations. There are a limited number of situations where a claim using this namespace URI and user.displayname source attribute will be pre-configured. It is advised this value and claim/attribute is checked, if not present by default, it will need to be defined.

Hybrid Azure Active Directory

  • I have never previously configured LDAP and wish to only use SAML

OR:

Azure Active Directory

  • I do not use LDAP and do not have an on-premise Active Directory

User Unique ID Attribute

http://schemas.microsoft.com/identity/claims/objectidentifier

Default claim added automatically when configuring an AzureAD Enterprise application with SAML Single Sign On.

Encoding

None

The encoding value is changed from None (which is the default) if not currently set. This is based on the User Unique ID Attribute using the default AzureAD claim http://schemas.microsoft.com/identity/claims/objectidentifier which the return value is not encoded.

User Principal Name Attribute

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Default claim added by default when configuring an AzureAD Enterprise application with SAML Single Sign On.

User Display Name Attribute

http://schemas.microsoft.com/identity/claims/displayname

Default claim used in certain situations. There are a limited number of situations where a claim using this namespace URI and user.displayname source attribute will be pre-configured. It is advised this value and claim/attribute is checked, if not present by default, it will need to be defined.

All other configurations

None

n/a

n/a

  • The Quick Start for all other configurations option does not set any default values, however it will remove anything previously defined in the User Unique ID Attribute and Encoding fields.

  • Fields and populated values are removed if different quick start options are selected.

  • If the incorrect quick start option had been previously used, it is recommended to manually remove the populated values in the User Unique ID Attribute, User Principal Name Attribute and User Display Name Attribute fields before selecting a new quick start option.

The values populated when selecting one of the quick-start options may not work in all cases. These values should be reviewed to ensure they are correct based on the SAML configuration and provider.

See below for explanations on each field (some of the fields have been discussed in the previous section, however additional information is provided below).

Field Name

Description

Intended Value

Domain Attribute

In order for AppsAnywhere to know which local domain the authenticating user is a part of, the name of a SAML attribute that contains this information may be provided.

If multiple LDAP connections have been selected, there are two main scenarios where this would be the case:

  • The username provided has no domain or short domain name suffix or prefix

  • The domain provided in the username is a federated alias

See below for more information about federated domain aliases.

NOTE: In the case where SAML only is used and the method has no associated LDAP connections, this field is mandatory. However if your IdP does not support or it is not possible to create a claim containing an attribute which contains the domain name, an arbitrary value can be provided.
However be aware that in this situation the UPN attribute must be provided (in the User Principal Name Attribute field) and present within the SAML response as the system will fallback to using the suffix of the UPN value obtained from the SAML AuthnResponse as the user's domain name. If this value is not present in the response or it is empty the user will be unable to login to AppsAnywhere.

The SAML-compliant attribute name in the SAML AuthnResponse containing the fully qualified domain name of the domain the user is part of, e.g. domain.edu

Note: This must be the attribute name and not the friendly name

Short Domain Attribute

The name of the SAML attribute made available to AppsAnywhere that the Short Domain can be retrieved from.

NOTE: In the case where SAML only is used and the method has no associated LDAP connections, this field is mandatory. However if your IdP does not support or it is not possible to create a claim containing an attribute which contains the short (NetBIOS) domain name, an arbitrary value can be provided. However be aware that in this situation the a value must be defined in the Short Domain Fallback Value field (detailed below).

The SAML-compliant attribute name in the SAML AuthnResponse containing the short (NetBIOS) domain name of the domain the user is part of, e.g. shortdomain

Note: This must be the attribute name and not the friendly name

Short Domain Fallback Value

This is the default value of the short (NetBIOS) domain name if the attribute cannot be retrieved from the SAML AuthnResponse.

A default value for the short (NetBIOS) domain name e.g. MYDOMAIN

User Unique ID Attribute

The name of the SAML attribute that is used as the unique user ID. This is used in pair with the Encoding field below.

The SAML-compliant attribute name in the SAML AuthnResponse containing the unique user ID, e.g. http://schemas.microsoft.com/identity/claims/objectidentifier

Note: This must be the attribute name and not the friendly name

Encoding

The encoding type of the User Unique ID Attribute field, this can either be None or Base64. Only set an encoding type if you are sure it is required.

None or Base64 depending on how the SAML attribute value is encoded.

Username Attribute

To determine the identity of the user, the username should be made available to AppsAnywhere within the SAML AuthnResponse returned by the identity provider. The name of this attribute can be provided here so that during the authorization process AppsAnywhere can extract this information.

Note: The Expected username format field must contain the correct syntax to match the format of the value this attribute will return.

The SAML-compliant attribute name containing the username in the SAML AuthnResponse, e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Note: This must be the attribute name and not the friendly name

User Principal Name Attribute

To determine the identity of the user, the name of the SAML attribute that is used to retrieve the User Principal Name value is also required.

Note: This value maybe the same as previously defined in the Username Attribute field if you prefer to use the UPN as the defined username format.

The SAML-compliant attribute name containing the user principal name in the SAML AuthnResponse, e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Note: This must be the attribute name and not the friendly name

User Display Name Attribute

The display name of the user should be made available to AppsAnywhere within the SAML AuthnResponse returned by the identity provider. The name of this attribute can be provided here so that during the authorization process AppsAnywhere can extract this information.

This is the display name your users will see on their AppsAnywhere profile.

The SAML-compliant attribute name containing the user’s display name in the SAML AuthnResponse, e.g. http://schemas.microsoft.com/identity/claims/displayname

Note: This must be the attribute name and not the friendly name

Federated Domain Aliases

In the event your users authenticate using a federated domain alias (i.e. the domain name portion of their login does not have a represented domain within your infrastructure) and only a single LDAP connection has been selected, a value for this field will be required in order for AppsAnywhere to know that this part of their login is not a real domain.

Note: This field is not required or used when no or more than one LDAP connection is selected. Any federated domain values specified in this field will be ignored in this case. Domain aliases can also be specified on the LDAP connection itself.

A list of valid domain names that corresponds to the federated aliases used in your user's usernames, e.g. myalias.com

If the domain found in the username matches this set value, then it will be ignored, and the domain associated with the selected (single) LDAP connection will be used instead.

These should be seperated by semi colons, e.g. myalias.com;anotheralias.com

When using SAML only (without an LDAP connection)

Configuring The Identity Provider Using Metadata

To make configuration of the identity provider easier, AppsAnywhere allows the importing of valid SAML 2.0 metadata in XML format. AppsAnywhere will attempt to deduce the correct values for the following fields:

  • Entity ID

  • Authentication Base URL

  • Single Sign-On Path

  • Certificate (X.509)

If using the metadata import functionality, beware that "Username Attribute Name", "Domain Attribute Name" and "Federated Domain Alias" will not be configured automatically.

At the bottom of the form you will find a section that allows you to do this, labelled Importing MetaData.

If you have the metadata of the identity provider to hand, you can copy and paste this into the provided text area and click the "Add MetaData to form" button. If the metadata is valid, the fields mentioned above will be populated accordingly. If you do not have the metadata available and do not have control over your SAML infrastructure, the person(s) responsible should be more than happy to provide this for you.

Filling the form in by importing metadata is not required in any way however, if you know what the information should be you can simply put them in manually.

Importing the metadata will not automatically save the SSO method for you, it'll just give you a helping hand filling out some of the fields! Once you have completed the remainder of the configuration, you can click save as you would normally.

Exporting The Service Provider Metadata

Once the new method has been saved in the system, you can generate the SAML metadata in XML format for this service provider. If the information contained in this saved method is valid, a text area will populated for you containing the metadata in its entirety; you will then be able to copy this and import it into your identity provider, or pass it to someone who can.

At the bottom of the form you will find a section that allows you to do this, labelled Exporting MetaData.

A button for automatically copying the metadata to your clipboard has been provided to make this easier, as can be seen in the image above.

Once configuration is complete, the next steps are Creating SAML Attribute Mappings and/or Importing directory entities then Provisioning