ADFS Integration with Keyfactor Command

Keyfactor Command can be configured to use Active Directory Federation Services (ADFS) using OpenID Connect (OIDC). By leveraging ADFS as the Identity Provider (IdP), organizations can centralize authentication, enforce policies, and provide secure access to Keyfactor Command. The integration involves configuring OIDC applications and relying party trusts in ADFS, followed by updating Keyfactor Command’s identity provider settings.

Please read through this entire guide before making any changes to your environments.

Important preconditions

Keyfactor Command

A few features of Command are not supported when using OAuth. The ones relating to enrollment are listed below. For information on other features, such as SSH and AD requester attribute tokenization in alerts, please refer to the Keyfactor Command documentation.

Enrollment Delegation turned off

Enrollment Delegation needs to be disabled for the Certificate Authority in Command.

Go to Locations > Certificate Authorities > Advanced and turn off Delegate Enrollment.

Use AD Template Permissions turned off

Depending on the version of Command you are using, this setting will either be on the Template or Enrollment Pattern level. The option to Use AD Template Permissions must be turned off.

ADFS

ADFS configuration changes

Command follows OIDC/OAuth security best practices that require exact issuer matching between discovery metadata and the issuer claim in tokens. This can be an issue in a standard ADFS deployment as, by default, ADFS will configure an access token issuer like http://…/adfs/services/trust and Command is configured for https://…/adfs; the mismatch breaks authentication.

In order to use ADFS with Command, changes need to be made to ADFS.

This could have implications for other applications that are leveraging your ADFS instance and should be reviewed with your ADFS Administrator before running.

The following command must be run to have ADFS issue consistent issuer patterns.

Set-AdfsProperties -Identifier "https://<your ADFS Server>/adfs"

In a standard, out-of-the-box ADFS configuration, this command changes the following value:

Command supports a single issuer/authority per IdP, and there is no product configuration to accept dual issuers. 

Prerequisites

• ADFS Server configured with SSL certificates
• ADFS Management Console Admin access
• Redirect UI for Command login callback
• Client ID and secret generated in ADFS

Configure OIDC on ADFS for Keyfactor Command

Step 1: Create an Application Group in ADFS

1. Open the ADFS Management Console.
2. Navigate to Application Groups and select Add Application Group.
   
   
3. Provide a name and select Server application accessing a web API. Then click Next.
   
   

Step 2: Add the Server Application

1. Provide a Name or leave as is.
2. Copy the Client Identifier and save it somewhere. It will be needed later.
3. Add Redirect URIs corresponding to Keyfactor Command's callback URL:
   https://<your command server>/KeyfactorPortal/callback/kfc-adfs
   
   
4. Click Next to generate a client secret. Save the client secret to a safe place.
   
   

Step 3: Configure Web API for relying party trust

1. Provide a name or leave the name as is.
2. Copy the client identifier saved from earlier and paste it into the Identifier field. Then click Add.
   
   
3. Configure access control policies. Select Permit everyone, as we are not configuring any MFA at the moment.
   
   

4. Enable OIDC scopes for the user authentication. Select the following scopes.

   • allatclaims
   • email
   • openid
   • profile

   

5. Click Next and verify the configuration.
6. Click Next to complete the setup.

Step 4: Define claim rules for Keyfactor

Define claim rules in ADFS to pass necessary attributes (such as UPN, email, or group membership) to Keyfactor Command. These claims will be mapped to users and roles inside Keyfactor.

1. On ADFS Console, access Application Groups. Then right-click the Keyfactor OIDC Integration > Properties.
   
   
2. Select Keyfactor OIDC Integration – Web API. Then click Edit.
   
   
3. Select Issuance Transform Rules. Then click Add Rule.
   
   
4. Select Send LDAP Attributes as Claims in the Claim rule template dropdown. (We are authenticating with on-prem AD, so we need to transform LDAP attributes as claims). Then click Next.
   
   
5. Provide a claim rule name.
6. Select Active Directory as the attribute store.

7. Map the following LDAP attributes to the corresponding outgoing claim types.

   LDAP Attribute	Outgoing Claim Type
   E-Mail-Addresses	E-Mail Address
   Display-Name	Name
   SAM-Account-Name	Common Name
   Token-Groups - Unqualified Names	Group
   User-Principal-Name	UPN

   

   You can also allow members of a specific group to authenticate by creating another rule.

8. Click Add Rule, and then select Send Group Membership as a Claims in the Claim rule template dropdown.
   
   
9. Provide a Claim rule name.
10. Click Browse to find the correct user's group.
11. For Outgoing claim type, select Group.
12. For Outgoing claim value, select group.
    
    

Step 5: Collect ADFS OpenID configuration information

Before configuring IdP in Keyfactor Command, we need to collect OpenID configuration from ADFS. To find the OpenID configuration:

1. Open the ADFS Management console, and select Service > Endpoints.

2. In the OpenID Connect section, note the URL Path of the OpenID Connect Discovery. 

   It will be in the following format: https://<your adfs server>/adfs/.well-known/openid-configuration.

   

3. Verify that you can reach the URL from a browser on the Command server.

Configure Keyfactor Command for OIDC

There are two options to configure the OIDC for command:

• Via the Keyfactor Command Portal Identity Provider settings
• Via the Keyfactor Command Configuration wizard

Option 1: Configure using Keyfactor Command Portal Identity Provider settings

Step 1: Configure the Import Discovery Document identity provider

In Keyfactor Command:

1. Navigate to System Settings > Identity Providers. Then click Add.
2. Select Generic in the Type field.
3. The Authentication Scheme name should match the endpoint of the Redirection URL on the ADFS Application configuration. In our case, it is kfc-adfs.
4. The Display Name can be anything. We provide kfc-adfs.
5. Select Global in the Permission Set field.
   
   

6. Select Parameters. Then click Import Discovery Document.

   The Discovery Document URL should be:

   https://<your adfs server>/adfs/.well-known/openid-configuration

7. Click Fetch. Then click Save.
   
   

   This should populate a few of the parameters. Some of the following may need to be added manually.

   Refer to your discovery doc (https://<your adfs server>/adfs/.well-known/openid-configuration) to see values for your environment.

   IDP Parameter Name	Value
   FallbackUniqueClaimType	sub
   OIDCScope	openid profile email
   NameClaimType	commonname
   UniqueClaimType	appid
   RoleClaimType	group
   ClientId	<your Client ID>
   ClientSecret	<your Client Secret>
   TimeOut	1000
   OIDCAudience	<your Client ID>
   Authority*	https://<your ADFS server>/adfs

   The Authority value is case sensitive and must match the issuer of the discovery document.

8. Click Save.

Step 2: Map claims to Keyfactor users

Map ADFS claims (such as email or UPN) to Keyfactor user identities. Group claims may be mapped to roles within Keyfactor to enforce access control.

1. Open System Settings > Security Roles and Claims in Keyfactor Command. Then select Claims.
2. Create a role claim for the group you specified in ADFS in the WebAPI Access Control Rule. Then click Add to create a claim.

3. On the Add Claim window, enter the following values.

   Name	Value
   Claim Type	OAuth Role
   Claim Value	<your group name>
   Provider	kfc-adfs
   Description	admins

4. Click Save.
5. Click Security Roles.
6. Select a role and click Edit.
7. Select Add and add the claim you just created.

Option 2: Configure using the Keyfactor Command Configuration wizard

Run the Configuration wizard and use the values from the discovery doc to fill in the values, as shown in the images below.

Test access

Verify the configuration by logging in to Keyfactor Command. You should be redirected to ADFS for authentication and then back to Keyfactor with a valid session.

You can test using idphint with the following URL:

https://<your Command server>/KeyfactorPortal/Login/Signin?idpHint=kfc-adfs

Troubleshooting

View the claims returned to Command

1. Put the Command Portal NLog into Debug mode.
2. Attempt to log in.
3. In the Command Portal log, search for "Claims returned" to see the claims that are being returned for the user trying to log in.
4. Verify the expected claims are being returned.
5. Put the Nlog file back in Info when you are done.

If the claims are being returned and the user is not getting roles assigned, be sure you followed the prerequisite steps to Set-AdfsProperties for the identifier.

Be sure you have checked with your ADFS administrator before you do this, as it could impact other applications using ADFS.

Refer to the prerequisites at the beginning of this document for more information.