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

   1. $rpt = "YOUR_HDC_INSTANCE_RP_DISPLAY_NAME"

   2. $webAppEndpoint = "https://my-hdc.bim.cloud/FederationMetadata/2007-06/FederationMetadata.xml"

   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.

Open

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:

https://my-hdc.bim.cloud/FederationMetadata/2007-06/FederationMetadata.xml

Verify that certificates are properly added by investigating these tabs:

Open

Claims configuration

 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:

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.

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

NameID

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 john.doe@domain.com 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:

 For HDC server 4.4 or newer, add Username mapper with NameID template:

E-mail

 Value s allowed in HDC Vversion 4.3 or older:

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

• email

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

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

• http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname

• http://schemas.xmlsoap.org/claims/UPN
  
   In version 4.4 or newer, any claim can be emitted as long as its properly registered in the Identity Provider mappings

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

Sample mapping:

Display name

 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):

• display_name

• "Display Name"

• http://schemas.xmlsoap.org/claims/CommonName

First name

 Required for HDC server 4.4 or newer

Last Name

 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.

 Configuration for servers running HDC version 4.3 or older

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

Full guide for MS ADFS https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-group-membership-as-a-claim

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

Sample:

Supported claims for groups:

• http://schemas.xmlsoap.org/claims/Group

• http://schemas.microsoft.com/ws/2008/06/identity/claims/role

• TGqbLDN

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. 

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

 Configuration for servers running HDC version 4.4 or newer

See: (sv) Add External group from SSO provider

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:

https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications

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 

https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-saml-claims-customization

Sending Groups as Claims from Azure based on JIRA example:

https://community.atlassian.com/t5/Jira-articles/SAML-Claims-Sending-Groups-to-Jira-from-AzureAD/ba-p/849863

Claims example in Azure console:

Troubleshooting

Access debug information

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

https://my-hdc.bim.cloud/debug

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 bim.cloud 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:

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

Simple config export

^{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.