How do I configure Refapp for Single Sign-on?

Configuring Refapp for Single Sign-on

Refapp supports single sign-on through the SAML 2.0 interoperability standard.

The vendors currently tested and supported are:

  • Azure Active Directory (Azure AD)
  • Microsoft Active Directory Federation Services (AD FS)

New section in Company Settings

As a Refapp Administrator, you can manage all the SAML SSO configuration from your Company Settings page and its SAML SSO Settings section.

The master switch is named Authentication via SAML SSO.

Authentication via SAML SSO

This is the master switch. When enabled and if there is valid metadata, logins via SSO will be enabled.

Disable user auto-provisioning for SSO

When turned on, new users will need to be created manually. When turned off, users are automatically created in Refapp when they log in the first time.

Login via password disabled when SSO is enabled

When this switch is turned on and SSO is enabled, users can no longer log in using their existing passwords.

SAML Entity ID

This is the entity ID for the service provider. If not set, it defaults to Refapp.

SAML Identity Provider xml Metadata

Paste the content of the xml metadata file that you download from your SAML service provider into this field.

This is what changes when SSO is enabled

  • Users can no longer log on using passwords (unless “Login via password disabled when SSO is enabled” is left in an off state) or change their passwords through Refapp. When the system detects a mail domain belonging to your company, the login user interface will change to show only a button that takes the user to your company login page. If the login is successful and it has been validated that the user is provisioned to use Refapp, they will be logged into Refapp and can use the system as usual.

  Skärmavbild 2022-08-17 kl. 14.20.18

  • Users can no longer be invited from the Refapp Users page.
  • The cached Refapp login token (stored in-browser) for SSO-enabled companies will expire after 24 hours (instead of 30 days for user/password logins) at which point the system will trigger a renewed login with your SSO system. This ensures that users can be offboarded properly.
  • If you need to expedite offboarding, you can delete a user from Refapp through the Users page after removing the user’s access to the application in the SSO application. All user sessions will be terminated immediately. If you keep the user’s access and remove the user from Refapp, a brand new user with the same name will be created at their next login. This will lead to confusion. 
  • If you have left the company setting Disable user auto-provisioning for SSO turned off, new users are onboarded automatically at login time and will be assigned the Default user access rights set on the Company Settings page. If they need extended permissions, your company’s assigned admin users need to perform that action through the Users page in Refapp after they have logged in the first time.  Skärmavbild 2022-08-17 kl. 14.31.22
  • Users get a new option to log out completely from the SSO provider at the bottom of the profile page.

Preparations

Ensure that you have set up the corresponding mail domains for SSO in Company Settings. Multiple domains, e.g. “brand1.yourcompany.com” and “brand2.yourcompany.com” are supported.

Skärmavbild 2022-08-17 kl. 14.32.44

Configuring Azure AD for Refapp SSO

  1. Create a “Non-gallery” Enterprise Application in the Azure AD Portal.  
  2. Add the following entries in the “Single sign-on” SAML pane:
    1. Identifier: Refapp (or something else that you choose and paste into the SAML Entity ID setting in Refapp Company Settings)
    2. Reply URLs:
    3. Sign on URL (optional): https://app.refapp.se/sso/saml... company id> - you get this value from the Refapp Company Settings page (SSO login address). This allows your users to initiate the Refapp login through e.g. https://myapps.microsoft.com
  3. Assign users/groups to the application according to your normal operating procedures.
  4. Download the “Federation Metadata XML” file. 
  1. Get in touch with Refapp support to set up a testing environment in our test.refapp.se environment.
  2. Provide the SAML Application Identifier (Entity Id) and metadata content in the Company Settings page on the test instance, turn on SAML SSO (“Authentication via SAML SSO) and test that login to Refapp works.
  3. Next, provide the same configuration on app.refapp.se and enable SSO.
  4. Let us know through a support ticket when the login via SSO works fine and we will reset all currently active user sessions to force them to login using SSO.

Configuring Microsoft Active Directory Federation Services for Refapp SSO

  1. Open the Refapp Company Setting page.
  2. Specify your wanted SAML Identity ID (or leave it blank) and save the settings.
  3. Click the “Download SAML Service Provider Metadata” button.
  4. Open the ADFS management console. This can be done from Server Manager as shown below: 
  5. Click the button on the right for Add a Relying Party Trust. 
  6. This opens a wizard for the trust with a welcome screen describing the feature. Review the description and click Start to begin.
  7. Import the SAML Provider Metadata file you downloaded previously. 
  8. Provide a display name for the Trust, “Refapp” or something similar is recommended and click Next.
  9. Finish the rest of the steps.
  10. We recommend two Claim Rules for brokering the SAML assertions. They can be added by first clicking the Add Rule button. 
  11. This first rule is an LDAP Attributes rule that ensures the required information is passed between the two systems. Configure the rule as shown below and click OK to save. (Make sure to use three separate fields for “E-Mail-Addresses, Given-Name, and Surname” or else some relevant info may be left as “None” later on.) 
  12. The second rule is a Transform rule. Refapp specifies urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress for the Format of the NameIDPolicy in Assertion Requests where ADFS natively expects these in Name ID format so we need to transform the format from email to Name ID. Select Transform an Incoming Claim from the drop-down and click Next to continue. 
  13. Input the configuration as shown below and click Finish. 
  14. Save the new claim rules by clicking OK.

Save the new claim rules by clicking OK.