Configure AD FS
Basic configuration performed on AD FS server
Register ADFS Relying Party Trust on your AD server
- Open AD FS console
- Open PowerShell window (As Administrator)
- Run the following commands
- $rpt = "YOUR_HDC_INSTANCE_RP_DISPLAY_NAME"
$webAppEndpoint = "https://my-hdc.bim.cloud/FederationMetadata/2007-06/FederationMetadata.xml"
Add-ADFSRelyingPartyTrust -Name $rpt -MetadataURL $webAppEndpoint
- 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.
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:
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.
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 email@example.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 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):
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"
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.
Current version reads both outgoing AD FS Roles and Groups. Direct Roles mapping is not supported!
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:
- Claim rule name: any name for this rule
- User's group: any group of users in your system, that you would like to share membership information with HDC
- Outgoing claim type: select Group
- Outgoing claim value: Any name that will be later on registered in HDC
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.
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:
- Add a new non-gallery application, give it a proper name, e.g. FM ACCESS
- Select Configure Single Sign-On
- Copy a URL to federationmetadata.xml generated for this application and send that to your HDC/FM Access system administrator
- Once you have received back a federationmetadata.xml for HDC/FMA, import it (via XML file) to Azure application
- This file contains all the necessary information, including certificates
- Review or customize the claims issued in the SAML token, make sure that
- Make sure that a minimum set of Claims required to complete login is issued:
- Name ID - must match user name used in your system
- Display Name
- Make sure that one of the supported tags is used
- Make sure that a minimum set of Claims required to complete login is issued:
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 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:
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:
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
- No labels