Configuring ADFS 5.0 as an OIDC Identity Provider for TechDoc 12

TechDoc's SAML authenticator has provided our users with a quick, easy, and unified Single Sign-On experience for years using the SAML (Security Assertion Markup Language) standard. As times have evolved, so has authentication. Over the last few years, the OpenID (OIDC) protocol has moved into the spotlight as the modern replacement for SAML. OIDC 1.0 is built upon OAuth 2.0 the current and mature version of the original OAuth 1.0 (Open Authorization) standard. TechDoc 12 now features a new OIDC authenticator that supports many of the current OIDC identity providers (IDPs) available including the latest version of Microsoft Active Directory Federation Services (ADFS) version 5.0 (available in Windows Server 2019 and newer). ADFS 5.0 includes both shared secret authentication as well as public/private key certificate-based authentication; the TechDoc OIDC authenticator supports both of these OIDC authentication methods. In this tutorial, we'll go over the steps needed to configure a TechDoc DM and ADFS and go over both authentication scenarios (shared secret and certificate-based authentication).

Setting up an Application Group in ADFS 5.0

Let's start by setting up an application group in ADFS that your TechDoc Document Manager (DM) will be a part of. If you already have an application group set up in ADFS that you plan to use, you may skip this section and add your TechDoc DM to that existing application group.

• Go to the server on which ADFS is installed and launch the AD FS Management application.
• Click on the Application Groups node on the left side.
  
  
  
  
• Click on the "Add Application Group..." link in the right pane to start the Add Application Group Wizard.
  
  
  
  
• On the "Welcome" step, give the application group a name; for this example, we called ours "TechDocApplicationGroup". Enter a description if desired, and select the template named "Server application accessing a web API" under the templates section. Click the Next button to continue.
  
  
  
  
• On the "Service application" step, enter the redirect URL for your TechDoc DM in the Redirect URI box:
  
  https://YOUR_TECHDOC_DM_HERE/servlet/td.web.OIDCRedirector
  
  Replacing YOUR_TECHDOC_DM_HERE with the full host name of your TechDoc DM. Click the Add button to add the URI to the list.
• Enter a description for this TechDoc DM instance if desired and note the Client Identifier generated for your TechDoc DM. The client identifier will be needed later when configuring the TechDoc OIDC authenticator. Create a text file and save the client identifier for later reference and click the Next button to continue.
  
• On the "Configure Application Credentials" step, you will need to decide which mechanism(s) you will be using to authenticate with. TechDoc can authenticate with ADFS using either a generated shared secret or a public/private key pair. You are free to configure both here at this time in ADFS, but TechDoc will only allow one mechanism to be used at once. Follow the steps below for the mechanism(s) you decide to use:

  Shared Secret

  • To configure a shared secret, check the box next to "Generate a shared secret". The generated shared secret will be displayed and can be copied to the clipboard ONLY now. If you loose the shared secret, you will have to generate a new one. Click the "Copy to clipboard" button and save this shared secret into the same text file you created earlier. Click the Next button to continue or follow the next step to additionally configure certificate-based authentication as well.
    
    
    
    

  Public/private key pair

  • To configure a public/private key pair, check the box next to "Register a key used to sign JSON Web Tokens for authentication" and click the Configure... button.
    
    
    
    
  • On the "Configure Keys or Certificates" window, you can elect to choose either a JWKS URL that advertises rolling certificates or upload individual certificates. If you already have a JWKS (JSON Web Key Set) service setup within your organization, you can enter the URL for that service here. When using the JWKS service, you'll need to get the corresponding latest private key over to TechDoc for use. For our example, we will upload a certificate of our own so select the "Select certificate" option and click the Add button.
    
    
    
    
  • On the "Select a JWT Signature Verification Certificate" window, navigate to the public certificate for the private/public key pair you intend to use. If you do not have the key pair yet, you can create a temporary key pair using openssl with the following options:
    
    openssl req -x509 -nodes -days 120 -sha256 -newkey rsa:4096 -keyout idp-metadata-adfs-private.key -out idp-metadata-adfs-public.crt -subj "/CN=YOUR_TECHDOC_DM_HERE"
    
    This generates both an x509 private key (-keyout idp-metadata-adfs-private.key) and public key (-out idp-metadata-adfs-public.cert), without a passphrase (-nodes) with an expiration set to 120 days from now (-days 120) specifically using SHA-256 (-sha256) with an RSA key size of 4096 (-newkey rsa:4096) and a subject using the same host name used for our TechDoc DM (-subj "/CN=YOUR_TECHDOC_DM_HERE") replacing YOUR_TECHDOC_DM_HERE with the fully qualified hostname of your TechDoc DM as before. A few things to note, the key must be set to require no pass phrase, the key must use SHA 256 and RSA. A smaller RSA key size (such as 2048) may be used if needed, but we suggest the max of 4096. Also, the expiration days should match what your ADFS setup is configured for. By default, the expiration days allowed are 365 but may be tightened by group policy. Additionally, you probably need to generate/obtain a fully qualified certificate instead of using a self-signed cert as in this example. This openssl example is meant only to get you up and running. Most organizations should already have access to the certificates they intend to sign with.
  • Once you have navigated to and selected your certificate, click the Open button.
    
    
    
    
  • Finally, click the OK button on the "Configure Keys or Certificates" window to complete the process.
    
    
    
    
• Now that you have configured your security mechanism(s), you can click the Next button.
• On the "Configure Web API" screen, enter the client identifier you noted in your text file earlier, and then click the Add button to add it to the list of identifiers. Enter a description if desired, and then click Next to continue.
  
  
  
  
• On the "Choose Access Control Policy" screen, choose the access policy needed for your environment. For this example, we're just going to use "Permit everyone", but you're free to choose another if needed. Choosing "Permit everyone" allows anyone to try and log into TechDoc. However, if they do not have an account configured in your TechDoc DM, they will not have an account to log into. Once you have selected your access policy, click the Next button to continue.
  
  
  
  
• On the "Configure Application Permissions" screen, you'll want to select all of the scopes that you want ADFS to return to TechDoc upon a successful authentication. By default, the "openid" should be selected and must be left checked. Additionally, you should check allatclaims, email, and profile. Once all four of these are selected, click Next to continue.
  
  
  
  
• On the "Summary" screen, review all of the information entered/chosen, and then click the Next button to continue.
  
  
  
  
• On the "Complete" screen, the application group has been successfully created. Click Close to close the Add Application Group Wizard.
  
  
  
  
• Back on the main ADFS window, you should now see the application group you just created. Click the application group in the middle pane, and then click "Properties" link in the right pane.
  
  
  
  
• On the application group properties window, double click the link under the Web API section.
  
  
  
  
• On the "Web API Properties" window, select the Issuance Transform Rules tab and then click the Add Rule... button.
  
  
  
  
• On the "Add Transform Claim Rule Wizard", select Send LDAP Attributes as Claims and then click the Next button to continue.
  
  
  
  
• On the "Configure Rule" screen, enter a name for the rule; we entered "Send User Attributes". Under the Attribute Store, Active Directory should be selected. Next select on the first line first column, E-Mail-Addresses (from the LDAP store) and then in the second column on the first line select E-Mail-Address (to map the LDAP email addresses to the email address claim). We'll also select Token-Groups as SIDs mapped to Group SID, User-Principal-Name mapped to UPN, and SAM-Account-Name mapped to uid. Refer to the screenshot below for the line and column mappings:
  
  
  
  
• Feel free to add any additional claims to be passed along to TechDoc, and then click the OK button to complete the rule.
  
  
  
  
• Click the OK button to close the Web API Properties window.
• Finally, click the OK button to close the application group properties window.
  
  
  
  
• This completes the ADFS side of the configuration, but before we move on to the TechDoc configuration we need to save a copy of the ADFS OIDC IDP metadata. Open a web browser so we can save a copy of the ADFS OIDC IDP metadata to a file for TechDoc. You should be able to enter in the address bar:
  
  https://YOUR_ADFS_HOST_HERE/adfs/.well-known/openid-configuration
  
  replacing YOUR_ADFS_HOST_HERE with the fully qualified host name of your ADFS instance. This should result in a screen that looks like this:
  
  
  
  
• Right click and select Save as... and save the metadata to a file in your TechDoc/etc folder; we named ours idp-metadata-adfs.json.

Setting up an OIDC Authenticator in TechDoc

• Open a web browser and navigate to your TechDoc Document Manager, log in as an Admin, and click on the Admin link on the top menu bar.
  
  
  
  
• On the Admin screen, click the Authenticator link under the Create... to start the creation of the TechDoc OIDC authenticator.
• On the Create Authenticator screen, enter a name for the authenticator and select OIDC from the drop down menu.
  
  
  
  
• For the service data, we'll need to specify one of the following service data lines. The first line is an example of how to configure an authenticator to use a shared secret:
  
  -midp-metadata-adfs.json -i893f153d-e2fd-4d22-94d8-e0e1eefce3d6a -sNYdPmQSJ2qPoOOrxD...
  
  where -m specifies the name of your metadata file, -i specifies your client identifier, and -s specifies your shared secret. The client id and secret should be in the text file from earlier. Optionally, you could also specify a service data string like the following to configure certificate based authentication:
  
  -midp-metadata-adfs.json -i893f153d-e2fd-4d22-94d8-e0e1eefce3d6a -pidp-metadata-adfs-private.key -Pidp-metadata-adfs-public.crt
  
  where -m specifies the name of your metadata file, -i specifies your client identifier, -p specifies the name of the private key file in your TechDoc/etc folder, and -P specifies the public key file in your TechDoc/etc folder. The client identifier should be in the text file from earlier. The names of your public and private keys may vary, and it's up to you to either generate these keys (as shown earlier) or obtain a public/private key pair from your organization.
• Once you've entered your service data, click the OK button to complete the creation.
  
  
  
  
• You may now click the Test link on the side menu, and then click the Test using... button to test your authenticator.
• You should see a list of user attributes returned that resembles the following:
  
  
  
  
• Most notably, make sure you see the entry named uid. This claim is the default one that will be used to map a windows user name to a TechDoc account. If a different claim is to be used, make sure that claim appears in the list. You may need to add the -n switch to your authenticator to specify the name of the specific claim you wish to use to identify users.
  
  
  
  
• If everything looks good, your configuration is complete! You are free to begin creating users using this authenticator by selecting it from the list on the create/modify user screen and entering their AD username (their uid or whatever other unique identifier you've chosen to use) in the field next to the authenticator.