Page tree
Skip to end of metadata
Go to start of metadata

Configure AD FS

Basic configuration performed on AD FS server

Register ADFS Relying Party Trust on your AD server

  1. Open AD FS console
  2. Open PowerShell window (As Administrator)
  3. Run the following commands
    2. $webAppEndpoint = ""

    3. Add-ADFSRelyingPartyTrust -Name $rpt -MetadataURL $webAppEndpoint

  4. Refresh AD FS console and select just created Relying Party Trusts "YOUR_HDC_INSTANCE_DISPLAY_NAME"

Configuration is automatically fetched from configuration URL provided in Point 3.b.

Certificates import

Properly imported certificates are critical for AD FS to work. Certificates will be used to sign SAML tickets exchanged between servers.

When registering Relying Party Trust using the scripts provided, certificates will be added and properly set. 

Certificates are obtained from repose to request sent to individual application address, like this:

Verify that certificates are properly added by investigating these tabs:

Claims configuration

(warning) This step is optional and required only for Groups / Roles mapping. These mappings are an example, and might not be imported to your server. 

These are sample files for claims configuration. AD group identifiers will NOT match ones on your server. Each rule must be edited and a proper group/role must be selected.

Copy these files to your AD FS server, into e.g. C:\Temp


Open PowerShell CMD as an Administrator and run the following command to import claims:

Set-AdfsRelyingPartyTrust -TargetRelyingParty $rp -IssuanceTransformRulesFile  ".\HDC-Issuance-Transform-Rules.txt" -IssuanceAuthorizationRulesFile ".\HDC-Issuance-Authorization-Rules.txt"

Check claims using AD FS console:

Now you can edit each claim to match your internal AD groups and roles.

You can create an Organizational Unit dedicated to HDC access control:

Minimum set of Claims required to complete login

There are several required claims that must be set in order to perform successful login and/or user registration.

(warning) It is very important to check your outgoing SAML request and make sure, that these tags are emitted. 


this should be mapped to parameter containing a user name that will be used in the system.

Value of this attribute must match user name used in HDC to reuse existing user accounts. 

Please note that current user account name can also be changed in case a new name should be used. 

For example, user "john" can be changed to in case email should be used as a user ID from now on. 

In all cases, user identifier must be delivered as NameID, even if its the same as e-mail. 

The tag should be emitted in the following form:

<NameID   Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">MyUserName</NameID>

(warning) For HDC server 4.4 or newer, ass Username mapper with NameID template:


(warning) Value s allowed in HDC Vversion 4.3 or older:

For e-mail, HDC will read the following attributes (allowed values):

The tag should be emitted in the following form (Name can be one of the values above):

<Attribute Name="" 
	a:OriginalIssuer="" xmlns:a="">

Sample mapping:

Display name

(warning) Only required for HDC server 4.3 or older

Display name will in most cases be a string containing user full name (First name + Last name - or other desired combination)

HDC will read these parameters (allowed values):

<Attribute  Name="" a:OriginalIssuer="" xmlns:a="">
      <AttributeValue>My Full user Name</AttributeValue>

First name

(warning) Required for HDC server 4.4 or newer

Last Name

(warning) Required for HDC server 4.4 or newer

Mapping AD FS roles and groups to HDC

Mapping groups and roles is optional. Having a proper mapping for at least one group can enable auto registration and login for new users.

More detailed security settings can be set using HDC interface. If this step is not performed, a new user will be registered, but will see "Unauthorized" message after initial login. 

The reason for this is that this individual will not have a minimum required role assigned, that is system Users.

(info) Configuration for servers running HDC version 4.3 or older

(warning) Current version reads both outgoing AD FS Roles and Groups. Direct Roles mapping is not supported!

Full guide for MS ADFS

Step 1: Add Claim Rule

Open your AD FS console, select proper Relying Party Trust and select Edit Claim Issuance Policy

Select Add Rule and choose type "Send Group Membership as a Claim"

Choose the following options:

  1. Claim rule name: any name for this rule
  2. User's group: any group of users in your system, that you would like to share membership information with HDC
  3. Outgoing claim type: select Group
  4. Outgoing claim value: Any name that will be later on registered in HDC


Supported claims for groups:

Last one stands for Token-Groups - Qualified by Long Domain Name

Step 2: Map incoming Groups in HDC

Each outgoing claim value can be mapped to external group in HDC

Go to Administrative panel and select Groups (in Users/Groups section), then Add Group. The External Name must match the Outgoing Claim Value exactly. 

These groups can be used directly or assigned to HDC Roles. To do that, go to Roles Manager, select a Role and Assign function. 

Users must have a proper Role (minimum HyperDoc User) to be able to login. Roles and group can also be assigned locally without using AD FS. 

In this example, a user that is a member of HDC Users (AD group), will be able to log in automatically with HyperDoc User role. 

(warning) AD FS groups cannot be used for "share" functions, as HDC cannot resolve members to be notified.

(info) Configuration for servers running HDC version 4.4 or newer

Mapping of groups from ADFS or LDAP providers must be done in Realm Management console. 

In order to create a mapping from specific claim to group or permission in HDC, please follow these steps:

Open realm Identity Providers

Select configured ADFS provider

Once a provider is selected, go to Mappers tab and select Create button to add 

Add new mapping

Add new mapping as shown below:

  • fill in the name - that can be any "friendly name" that will let you understand later on what is this mapping about
  • select mapper type: SAML Attribute to Role
  • Type in Attribute name: this is the attribute that will be emitted from ADFS. This is just an example it might be different on your ADFS instance
  • Type in Attribute Value: a group name that is emitted from ADFS
  • Select value from available Roles/Groups/Permissions

(warning) Note: mapping can be made to group (recommended) but also directly to permission or permission set but in that case it will be harder to track and manager later on in application interface. 

Azure AD / ADFS / SAML 2.0

Azure setup support is based on SAML 2.0 standard.

Overview of the configuration

Please follow these steps to configure single sign-on to your application:

Summary of steps:

  1. Add a new non-gallery application, give it a proper name, e.g. FM ACCESS
  2. Select Configure Single Sign-On
  3. Copy a URL to federationmetadata.xml generated for this application and send that to your HDC/FM Access system administrator
  4. Once you have received back a federationmetadata.xml for HDC/FMA, import it (via XML file) to Azure application
    1. This file contains all the necessary information, including certificates
  5. Review or customize the claims issued in the SAML token, make sure that 
    1. Make sure that a minimum set of Claims required to complete login is issued:
      1. Name ID - must match user name used in your system
      2. email
      3. Display Name
    2. Make sure that one of the supported tags is used

Now you can attempt to login. Remember, that roles mapping is needed for users to be auto registered. 

Customize claims issued in the SAML token

Sending Groups as Claims from Azure based on JIRA example:

Claims example in Azure console:


Access debug information

To verify login problems,  use debug URL as follows (after login attempt):

If you are authenticated, but cannot access the system, please review claims visible in the debug output carefully. 

Wong claims is the most common source of problems with ADFS login. 

Check ADFS log

On AD FS server, open Event Viewer and go to Application and Services Logs → AD FS → Admin

This event log should contain some entries if the login was unsuccessful.

Certificates revocation check

Certificates used by ADFS connection on are private certificates (not signed by top level authority).

A proper revocation check level must be set, otherwise certificate validation will always fail.

To check this setting, you can run the following command in ADFS server Power Shell:

  • Get-ADFSRelyingPartyTrust -Name "YOUR_HDC_INSTANCE_RP_DISPLAY_NAME" | fl name, *revocation*


Settings that should work are as follows:

EncryptionCertificateRevocationCheck : CheckChainExcludeRoot

SigningCertificateRevocationCheck    : CheckChainExcludeRoot


  • Possible values are:
  • None
  • CheckEndCert
  • CheckEndCertCacheOnly
  • CheckChain
  • CheckChainCacheOnly
  • CheckChainExcludeRoot
  • CheckChainExcludeRootCacheOnly


To fully disable revocation check, at least for test, you can run this on Power Shell command:

  • Set-ADFSRelyingPartyTrust –TargetName “YOUR_HDC_INSTANCE_RP_DISPLAY_NAME” –SigningCertificateRevocationCheck “None”

Force update certificates

If the certificates are potentially wrong or old (or simply different from what they should be), a forced update might be required.

Run these commands as an administrator to update certificates from you HDC instance:

$rptUpd = Get-AdfsRelyingPartyTrust -Identifier "RELYING_PARTY_IDENTIFIER"
$webAppEndpoint = ""
Set-AdfsRelyingPartyTrust -TargetRelyingParty $rptUpd -MetadataUrl $webAppEndpoint
Update-ADFSRelyingPartyTrust -TargetRelyingParty $rptUpd 


SP Entity ID is usually a URL or other identifier given by the Service Provider (SP) that uniquely identifies it. It's often part of a metadata file (an XML file with a certificate, entity ID, and endpoint URLs). You should be able to request this from the SP.

Export configuration data

In case we cannot see any obvious issues with customer configuration, it might be useful to analyze configuration step by step.

To do this, please export configuration and send the files for inspection.

To verify your configuration, we would ask you to perform the following commands, using Power Shell:

  • Please change the “YOUR_HDC_INSTANCE_RP_DISPLAY_NAME” below to the name that you have used to register the service on your side

(These name must match exactly, so that the proper configuration is exported)

  • Run these commands:
    • $SourceRelyingPartyTrust = "YOUR_HDC_INSTANCE_RP_DISPLAY_NAME"
    • Get-ADFSRelyingPartyTrust -Name $SourceRelyingPartyTrust | Export-Clixml "HDC-customer_name-TEST.xml"
    • Get-ADFSRelyingPartyTrust -Name $SourceRelyingPartyTrust | Export-Csv -Path "HDC-customer_name-TEST.csv"


Please send back the resulting files: HDC-customer_name-TEST.xml and HDC-customer_name-TEST.csv

Authentication issue instant is too old or in the future

Invalid date in Authentication ticket (ticket is too old or in the future). Please re-login. 

This message is shown when the Authentication ticket was received successfully, but the date check failed.
The ticket cannot have a future date and cannot be older than number of 7 days (this date can be configurable if needed but it's not recommended to prolong token life for security reasons).

Please logout and login again in the AD to refresh the ticket.
If the problem persists, please contact your system administrator who should check if system clocks are set correctly.


HDC server side configuration

ADFS configuration - HDC side

  • No labels