Single sign-on (SSO) allows users to log into the Application Manager using an existing identity without the need to remember additional login data. The user identity can be provided from various sources (e. g., Google Workspace, your own active directory, etc.). We utilize SAML 2.0 (Security Assertion Markup Language) in order to provider a secure and standardized single sign-on mechanism. Read below the steps necessary in order to setup SSO with SAML 2.0.

SAML setup

Step 1: Log into Application Manager and go to ´Settings´ (1) > ´Integrations´ (2) > ´Single sign-on´ (3). Find the link to an XML schema containing all necessary information to configure your SAML 2.0 identity provider under ´Service provider XML´ (4).

Step 2: Now setup your SAML 2.0 identity provider (IdP). This step may vary slightly depending on which IdP you are using.

Regardless of which provider you use, in this step you should download an appropriate SAML 2.0 IdP metadata XML file containing a valid certificate so that you can upload it to onlyfy.

Please contact your IT administrator if you need help with this.

Find the path to the appropriate instructions in this overview:

Identity provider	Link to the guide
Google Workspace (formerly known as Google Apps or G Suite)	Benutzerdefinierte SAML-App einrichten
Microsoft Active Directory with AD FS (Active Directory Federation Service)	Configure a SAML 2.0 provider for portals with AD FS
Microsoft Azure AD	Configure a SAML 2.0 provider for portals with Azure AD
OneLogin	Using OneLogin as SAML Identity Provider

The identity provider metadata XML file should have the following format. This is an example from Google Workspace:

<?xml version="1.0" encoding="UTF-8" standalone="no"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://accounts.google.com/o/saml2" validUntil="2022-02-28T14:34:20.000Z">  <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">    <md:KeyDescriptor use="signing">      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">        <ds:X509Data>          <ds:X509Certificate>CERTIFICATE</ds:X509Certificate>        </ds:X509Data>      </ds:KeyInfo>    </md:KeyDescriptor>    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://accounts.google.com/o/saml2/idp"/>    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://accounts.google.com/o/saml2/idp"/>  </md:IDPSSODescriptor></md:EntityDescriptor>	

Please note:

• Metadata XML file
  - WantAuthnRequestsSigned should be false!
  - When configuring Windows Azure the "Reply URL" should be the ACS-URL (AssertionConsumerService) found in the XML described in step 2.

• SAML Response
  - The main assertion must include the authentication statement: AuthnStatement.
  - The InResponseTo attribute must be included and should contain the ID from the SAML Request.

The following steps assume, that you have generated a valid SAML 2.0 IdP metadata (certificate) file.

Step 3: Go back to Application Manager > ´Settings´ (1) > ´Integrations´ (2) > ´Single sign-on´ (3) and click on ´Add identity provider´ (4) at ´SAML 2.0 Identity providers´.

Fill in the required information, paying attention to the following fields:

1. USER ATTRIBUTE: This field defines, which attribute of the Application Manager user is used for authentication: email or active directory username. 
   
   
2. SAML-RESPONSE ATTRIBUTE: With this field you can select which XML response attribute (containing the identifying information) we should use for authentication. The following options are available:
   - Subject Name-ID
   For example:

   <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">user@example.com</saml:NameID>

   - Custom Attribute Statement
   In case of a custom attribute statement, the name must match your identity provider configuration. For example: If you are returning a user field named "EmailAddress" (this is the default in many cases), it must have the same name in the Application Manager SAML configuration. Some identity provider solutions use the full URL schema as naming convention e. g.: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   
   
3. METADATA FILE: Upload in this field your metadata file.

After you have filled in everything, click ´Save´. Log out of Application Manager and now you should be able to sign in using your configured identity provider.

Things to consider after the setup

• If you are using Google Workspace (formerly known as Google Apps or G Suite) as identity provider it can take up to 24 hours on their side to activate new configurations or changes.
• By default, adding a SAML 2.0 identity provider results in deactivating the possibility to login manually by using your Application Manager login credentials. If you want to provide both login possibilities simultaneously, please contact our support team.

Troubleshooting

• 404 page: If you are experiencing a "404" error message after getting redirected to Application Manger after a successful login, please check if the username (in most cases the email address) of the user matches the one in your active directory. Also check, if the username in your SAML response is passed in the correct SAML attribute (NameID or custom attribute) according to your configuration in Application Manager.
  
  
• Other errors: If you have configured everything according to our guidelines and still experience any errors, please contact our support team. In order to solve your issue faster, please try to include the following information in your support request:
  - Date and time when the SSO / SAML login process was started (when you clicked the SSO button in our login mask).
  - Date and time when you got redirected to our ACS URL.
  - When possible: please attach the unencrypted SAML response.