Active Directory Federation Services (or short, ADFS) is a software technology developed by Microsoft which can be used as part of logical access control to data systems by using a Single Sign On method. Single Sign On (or short, SSO) means that a User logs in to a system with a username and password, and can access other various systems after logging in. Carerix has the option to control the access via ADFS.

How does ADFS work with Carerix?

The setup for ADFS is done by the customer’s ADFS administrator and an expert from Carerix. The technical guide gives more details about this.

After the setup is successfully done, for the end User, ADFS works as follow:

  • A User opens the Carerix system.
  • If the User is already logged in into ADFS, the Carerix system will also log the User in and the application can be used.
  • If the User is not already logged in into ADFS, Carerix will redirect the User to the ADFS login page.
  • After logging in, the User is redirected back to Carerix, and logged in there.

The rights for Users to access the Carerix system or not are administered within the ADFS system. This means that only Users within ADFS can be granted access and that access to the data in Carerix relies on the availability of the ADFS system.

Emergency access ADFS

If ADFS is unavailable, it is possible to —temporarily— disable ADFS within Carerix so that Carerix data can be accessed:

  • A request to disable ADFS needs to be sent  to the Carerix support desk. Only a few administrators are able to send such a request.
  • Carerix Support will verify the identity of the requester.
  • Carerix Support will disable ADFS via a database operation.
  • For one admin user, a password will be set via a database operation.
  • The password will be given to the requester and has to be changed upon first login.
  • The Administrator can then determine what to do with the other existing Users.

Carerix Support

Carerix support is available from 08:30 till 17:30 CET/CEST via email and chat. Phone support is available from 08:30 till 17:00 CET/CEST. Incoming support requests are reviewed and prioritised within 15 minutes. An emergency number is available from 07:00 till 22:00 CET/CEST which may be used when ADFS is unavailable.

Remarks

  • Carerix Customer Support needs a User account administered within ADFS with rights to login into Carerix in order to perform support.
  • If Premium Disaster Recovery is used, whitelist the IP’s from our failover location for use with ADFS.

ADFS Technical Guide

General ADFS login flow

  • User opens a Carerix app page, e.g. http://publictest.carerix.net where publictest is customers system name(we’re going to use publictest as an example through the whole document).
  • If the User doesn’t have an authorization cookie, the system redirects to the Carerix ADFS Service Provider, located at https://adfs.carerix.com/.
  • If the User hasn’t been authorized by the Service Provider, he’s redirected to the ADFS login page, located on customers server, which is configured for publictest
  • If the User is not authenticated by the customers ADFS server, the login page is shown, asking for valid credentials.
  • If the User is authorized by the customers ADFS server, he gets redirected to the Carerix ADFS Service provider, which validates the request and stores users attributes in case login was successful.
  • If the login was successful, and User’s attributes are stored, the Carerix ADFS Service Provider redirects the User back to the Carerix application ADFS login method.
  • The Carerix back-end checks passed parameters and logs User in, sets an authorization cookie, in case user with given attributes can be logged in.
  • In case login was successful, user can start using the Carerix application.

Customer setup

To this point, consider customer has the Active Directory configured and ADFS enabled, so that only configuration with Carerix is needed.

There are two steps needed to configure communication between customers ADFS server and Carerix Service Provider: Add a relying party trust and Set up claim rules.

1. Provide Metadata.xml

  1. Obtain "metadata.xml"
    Usually, you can obtain the Metadata.xml by calling an URL like https://localhost/FederationMetadata/2007-06/FederationMetadata.xml on your ADFS server.
    Please consult your own documentation for the exact URL.
  2. Send this Metadata.xml to Carerix.
    Carerix will add your information to the Carerix ADFS gateway configuration.

2. Add a relying party trust.

To Add a Relying Party Trust, the  ADFS administrator needs to get metadata that is provided by Carerix Service Provider. It’s generated automatically, based on the Carerix’s system configuration. It can be accessed by following link: https://adfs.carerix.com/module.php/saml/sp/metadata.php/{$customer_name}?output=xhtml

Where {$customer_name} is the exact same value for which we’ve configured Service Provider.

That step has to be done by customers ADFS server administrator.

To check if it was added successfully:

  1. Open https://adfs.carerix.com/module.php/core/authenticate.php?as={$customer_name}&output=xhtml
  2. Get redirected to ADFS login page, you have to see the login form, or get redirected back if you were already authenticated.
  3. You’ll end up in Carerix system with an error, because no claim rules were defined. So open again https://adfs.carerix.com/module.php/core/authenticate.php?as={$customer_name}&output=xhtml , you have to see something like this.

Where ‘Your attributes’ will contain configured claims, after they’re configured.

3. Set up claim rules in the ADFS server configuration.

That step has to be done by customers ADFS server administrator.

To check what claims are passed, do the following instructions. Open https://adfs.carerix.com/module.php/core/authenticate.php?as={$customer_name}&output=xhtml where 'Your attributes' contains claims that are configured in the ADFS server.

When they're configured the User has to do the login again.

The first column is a claim name, and the second is claim value. There has to be at least one attribute, that's going to be used as a Carerix user name. That has to be the exact value from adfs.adfsMapping userName value.

NB: That userName claim(attribute) is a minimum requirement for ADFS login to work.

Note: The authorization is saved in Service Provider session, so if you refresh the page(by pressing Ctrl+R or F5), you'll see credentials restored from session. That way, if you update claim rules in your ADFS server, you won't see them on that page until you relogin. Of course, you can click 'Logout' but then you'll get logged out of the ADFS too. So the easiest way to work with that will be to clear cookie and refresh the page. 

Steps to clear cookie:

- Hit F12 to open developer tools

- click 'Resources'

- choose 'Cookies->wave1.adfs.carerix.com' in left panel

- select SimpleSAMLAuthToken in cookies list and hit Del.

Then you can just refresh the page and login flow will be performed automatically, finally you'll see the page with updated Attributes list.

____
Keywords: UD-2993

Did this answer your question?