A few things you should know before starting the deployment.
As part of your onboarding with Keyless, you should have performed the steps below:
Provide the Keyless IT department with the domain name of your ADFS service.
Update the ADFS configuration to trust the domain names of the Keyless SAML connectors (SP & IdP) that Keyless provided you with.
Ensure that the firewall policy of your local network allow the following:
The ADFS service must be reachable by our SP and IdP.
For account linking, the user browser must be able to communicate with the SP and the ADFS instance.
For authentication, the user browser must be able to communicate with the IdP and the ADFS instance.
The EUD must be able to communicate with the Keyless Infrastructure.
If you think that you are missing one or more of theses prerequisites, please reach out directly to support@keyless.io.
Integrating Keyless with Active Directory Federation Services
This guide details the steps required to configure Keyless for your ADFS instance. Integrating Keyless with ADFS is a simple 2-step process that you can get up and running in less than 10 minutes.
This guide assumes that you have experience installing and configuring Windows Server 2016 or 2019, Active Directory, and Active Directory Federation Services (ADFS) 2016 or 2019.
For more information on installing ADFS, please see the ADFS 2016 Deployment Guide.
Login to your ADFS Management portal from your Server Manager by clicking "Tools" from the top navigation bar and selecting "AD FS Management
Once you are in the AD FS Management Portal, right click on “Relying Party Trust” and select “Add Relying Party Trust…” from the right-pane menu, as shown in the image below.
This will open a 5-step wizard. In the first step of the wizard, select the default value of “Claims Aware” and click “Start”.
In the following screen, import data about the relying party published online. Enter your metadata URL which was provided during the provisioning of your account. For this example we are using https://contoso-poc-registration.keyless.technology/metadata/
where <contoso-poc>
represents the handle used to identify your instance.
For provisioning questions, contact support@keyless.io
After inserting the URL, click “Next”.
You may now optionally change the Display name for the relying party, and add an optional note. This is a friendly name that will be displayed to administrators in the AD FS console and to end users. Click “Next” once done.
In the next step, you will be required to define the access control policy, this will configure which user and groups will be able to register and use Keyless. After selecting the proper users and groups, click “Next”.
The next step, called “Ready to Add Trust”, is an overview of the configuration from the previous steps. Please take a minute to review the parameters configured and click "Next" when ready.
In the last step, leave the checkbox checked. When done, click “Close” and finish the process of adding the Relying Party Trust.
After completing Step 1 above, you should be able to see the new relying party trust you’ve just created under the “Relying Party Trusts” folder in your AD FS Management Portal.
Right-click on the relying party trust you’ve just added, and select “Edit Claim Issuance Policy” from the menu.
In this step you will define the rules that will transform the claims sent to the Keyless relying party.
Go ahead and define two rules by clicking “Add Rule” in the bottom part of the dialog:
Rule 1: Send UPN as Email Address
Rule Type: “Send LDAP Attributes as Claims”
Rule Name: “Send UPN as email address”
LDAP Attribute: User-Principal-Name
Outgoing Attribute: E-mail Address
After clicking "Finish" you should see the following rule:
Rule 2: Send UPN as NameID
Rule Type: “Send LDAP Attributes as Claims”
Rule Name: “Send UPN as NameID”
LDAP Attribute: User-Principal-Name
Outgoing Attribute: Name ID
After adding these two rules, you should see the following list of rules in the “Issuance Transform Rules” dialog.
Click "Apply" and "OK" to save your changes.
If you would like to configure Keyless as an MFA method for your ADFS connected applications, go to the next chapter "Authentication".
Integrating Keyless with Active Directory Federation Services
This integration provides a Keyless multi-factor authentication prompt to web-based logins through an AD FS Identity Provider and/or Web Application Proxy. After completing primary authentication to the AD FS server , your users will be required to complete a Keyless challenge before getting redirected back to the relying party.
A high-level architecture diagram of the integration can be found below.
Common issues and solutions for Keyless and ADFS integration.
Please confirm that you are able to reach https://<customer>-registration.keyless.technology/metadata/
from your network, where <customer> is the domain given to you by Keyless.
Select the <customer>-registration.keyless.technology ‘Relying Party Trust’ in ADFS
Click on ‘Edit Access Control Policy'
Select ‘Permit specific group'
Please open PowerShell as administrator on your ADFS and enter this command:
On the ADFS ‘Home Realm Discovery’ screen, the browser on users’ devices may cache the list of login options. Clearing the cookies in the browser solves the problem.
Configure Keyless as an MFA method for your ADFS connected applications.
This guide details the steps required to configure Keyless to be used as the authentications method for your ADFS instance.
This guide assumes that you have experience installing and configuring Windows Server 2016 or 2019, Active Directory, and Active Directory Federation Services (ADFS) 2016 or 2019.
Login to your ADFS Management portal from your Server Manager by clicking "Tools" from the top navigation bar and selecting "AD FS Management
Once you are in the AD FS Management Portal, right click on “Relying Party Trust” and select “Add Relying Party Trust…” from the right-pane menu, as shown in the image below.
This will open a 4-step wizard. In the first step of the wizard, select the default value of “Claims Aware” and click “Start”.
In the following screen, import data about the claims provider published online. Enter your metadata URL which was provided during the provisioning of your account. For this example we are using https://<acme-idp>.keyless.technology/metadata/
where <acme-idp>
represents the handle used to identify your instance.
You may now optionally change the Display name for the claims provider, and add an optional note. This is a friendly name that will be displayed to administrators in the AD FS console and to end users. Click “Next” once done.
The next step, called “Ready to Add Trust”, is an overview of the configuration from the previous steps. Please take a minute to review the parameters configured.
After completing Step 1 above, you should be able to see the new Claims Provider Trust you’ve just created under the “Claims Provider Trust” folder in your AD FS Management Portal.
Right-click on the Claims Provider Trust you’ve just added, and select “Edit Claim Rules” from the menu.
In this step you will define the rules that will transform the claims sent to the AD FS from Keyless.
Go ahead and define three rules by clicking “Add Rule” in the bottom part of the dialog:
Rule 1: Pass through Name ID as Windows account name
Rule Template: Transform an incoming claim
Claim rule name: “Pass through Name ID as Windows account name"
Incoming claim type: Name ID
Incoming name ID format: Unspecified
Outgoing claim type: Windows account name
Select the "Pass through all claim values" bullet button.
Rule 2: Pass through Name ID as UPN
Rule Template: Transform an incoming claim
Claim rule name: “Pass through Name ID as UPN"
Incoming claim type: Name ID
Incoming name ID format: Unspecified
Outgoing claim type: UPN
Select the "Pass through all claim values" bullet button.
Rule 3: Set Group Keyless
Rule Template: Send Claims Using a Custom Rule
Claim rule name: “Set Group Keyless"
Custom rule:
c:[]
=> issue(Type = "http://schemas.xmlsoap.org/claims/Group", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = "keyless", ValueType = c.ValueType);
Click "Apply" and "OK" to save your changes.
Please open PowerShell as administrator on your ADFS and enter this command (after replacing <keyless-registration-domain>
with the domain provided to you by Keyless):
This assumes that there is at least one user already enrolled with Keyless and that can be used for this test.
Go to https://<your-adsf-domain>/adfs/ls/idpinitiatedsignon.htm
and select the "Sign in to this site" option.
Click on the identity provider associated with Keyless IdP:
Here, provide the username (UPN format) of the test user and click the 'Continue' button.
At this point, the user should receive a push notification to the Keyless Authenticator app on his mobile phone. Once authenticated on the phone, the user should be logged in.
Please complete before moving on to this guide.
For more information on installing ADFS, please see the .
For provisioning questions, contact io