29.2 Single Sign-On with ADFS

Before starting working on Active Directory Federation Services (ADFS), let us see how to install and then configure it on your system and then get ready to work on it with OpKey.

Installing ADFS o Windows Server 2012 R2

ADFS is a well-known service for providing Single-Sign-On (SSO) facilities to multiple web applications using a single Active Directory account.

Follow below-given steps to install ADFS on Windows Server machine:

Open Server Manager and click on Add Roles and Features under Manage menu.

Click Next.

Select Role-based or feature-based installation and then click Next.
Select the server you want to install this role then click Next.

Note: Web Application Proxy role and ADFS cannot be installed on the same computer.

Select Select a server from the server pool and then click Next.

You can select other required features from here. Select Active Directory Federation Services and click Next.

Click Next.

Click Next.

The ADFS role does not required a reboot.
Click Install to proceed the ADFS installation process.

Once the ADFS installation has finished, click Close.

Configuring ADFS on Windows Server 2012 R2

Follow below given steps to configure the ADFS

Navigate to the Server Manager under Notifications button. Click the message Configure the federation service on this server.
Post-deployment Configuration popup message appears.

As we have to create the new federation server (as our first ADFS server), select the first option then click Next.

Make sure that the account you are logged into has Active Directory Domain Admin permissions. If not then click Change.
Click Next to continue.

SSL Certificate: On the drop down menu you will see the certificates installed on the server. You can use the default self signed or use one you create. Ensure you have it in .PFX format.
Federation Service Name: Give your AD FS a FQDN name.
Federation Service Display Name: Enter a display name.
Click Next to proceed.

Note: If you are installing ADFS on a Domain Controller or want to use a different FQDN for ADFS than the server you will need to ensure the name you enter has a DNS Record created.

Since this is my home lab I am putting ADFS on my Domain Controller and needed to create a DNS entry.

Note: If you imported a certificate, you can see it is added to your Personal Certificates.

On the Specify Service Account tab you may get the following message.
If you want the Wizard to create a Service Account for you then proceed to the PowerShell window below. If you want to create a Service Account manually you can add it by selecting the second option.

PowerShell Commands:

Get-Help Add-KdsRootKey – Read about the command
Add-KdsRootKey -EffectiveImmediately – Generate root key

Enter the Service Account you want to use and click Next:

Note: Ensure this user account is added to the local administrators group of your ADFS server. It is required to setup Microsoft Web Application Proxy.

You have the option of using a Windows Internal Database (WID) or SQL Server. If you have a small environment/lab then use WID. If you have a large environment use a SQL database.
Click Next.

Note: WID is a limited version of SQL Express that doesn’t have a GUI or management interface. The WID database is a file (SUSDB.dbf) stored in C:\Windows\wid\data\

Click Next.

If everything is check out, click Configure.

Once complete click Close.

ADFS is now installed and is ready for testing!

Let us see if ADFS is working properly.

Open a web browser and go to the ADFS URL below and click Sign In.

https://adfs.virtualtesting.com/adfs/ls/idpinitiatedSignOn.aspx

You should get a login box, enter your domain credentials, once logged in you should show the below screen:

You are now ready to use ADFS in your environment!

Adding a Relying Party Trust

(1) Open Server Manager > Navigate to the Tools menu > click on it and select ADFS Management option from dropdown.

(2) Click on Add Relying Party Trust under Trust Relationships of AD FS in ADFS management sidebar.

(3) Add Relying Party Trust Wizard opens. In the Welcome screen, click Start to continue.

(4) Click Start to continue.

(5) Select the Enter data about the relying party manually option in the Select Data Source screen.

(6) Click Next to continue.

(7) Specify Display Name screen appears. Enter a Display Name to recognize the trust, such as Test Environment, and add any notes you want to make.

(8) Click Next to continue.

(9) Select the AD FS profile option in the Choose Profile screen.

(10) Click Next to continue.

(11) Leave the certificate settings at their default values in the Configure Certificate screen.

(12) Click Next to continue.

(13) Select the option Enable Support for the SAML 2.0 WebSSO protocol and enter the SAML 2.0 SSO service URL in the Configure URL screen. (Format should be – https://<your-mattermost-url>/login/sso/saml where https://<your-mattermost-url>)

(14) Click Next to continue.

(15) Enter the Relying party trust identifier (also known as the Identity Provider Issuer URL) in the Configure Identifiers screen. (Format should be – https://<your-idp-url>/adfs/services/trust).

(16) Click Add to add the entered Relying party trust identifier in the list.

(17) From here at Configure Multi-factor Authentication Now screen, you can enable multi-factor authentication.

(18) Click Next to continue.

(19) Select the option Permit all users to access this relying party in the Choose Issuance Authorization Rules screen.

(20) Click Next to continue.

(21) You can review your settings in the Ready to Add Trust screen.

(22) Click Next to continue.

(23) From this Finish screen, select the Open the Edit Claim Rules dialog for this relying party trust when the wizard closes option, and .

(24) Click Close.

Create Claim Rules

(1) Launch Edit Claim Rules for Test Environment. Open the Issuance Transform Rules tab and click the Add Rule… button.

(2) Add Transform Claim Rule Wizard opens.

(3) Select Send LDAP Attributes as Claims from the drop-down menu inn the Choose Rule Type screen. Click Next to continue.

(4) Enter a Claim Rule Name of your choice, select Active Directory as the Attribute Store in the Configure Claim Rule window.

(5) Fill the required fields in Mapping of LDAP attributes to outgoing claim types as mentioned below:

From the LDAP Attribute column, select E-Mail-Addresses. From the Outgoing Claim Type, type Email.
From the LDAP Attribute column, select Given-Name. From the Outgoing Claim Type, type FirstName.
From the LDAP Attribute column, select Surname. From the Outgoing Claim Type, type LastName.
From the LDAP Attribute column, select SAM-Account-Name. From the Outgoing Claim Type, type Username.

The FirstName and LastName attributes are optional.

Note: The entries in the Outgoing Claim Type column can be chosen to be something else. They can contain dashes but no spaces.

(6) Click Finish to add the rule.

(7) Here, you can see that the added Claim Rule is displaying in the list.

(8) Click Apply and then OK to continue.

(9) Create another new rule by clicking the Add Rule button.
(10) In the Choose Rule Type screen, select Transform an Incoming Claim from the drop-down menu.

(11) Click Next to continue.

(12) Enter the desired Claim Rule Name in the Configure Claim Rule page.

Select Name ID for the Incoming claim type
Select Unspecified for the Incoming name ID format
Select E-Mail Address for the Outgoing claim type

(13) Moreover, select the Pass through all claim values option. Click Finish.

(14) Here, you can see that the added Claim rule name is displaying in the list.

(15) Click on Apply and then OK to continue.

(16) Here, all the added Relying Party Trust are displaying in the list.

(17) Right click on your Relying Party Trust and then click on the Properties option.

(18) Select the Endpoints tab & then select your endpoint to open it.

(19) Select Redirect in Binding. Click OK to finish.

(20) Open your ADFS URL on the web browser.

(21) Select your site from Sign into one of the following sites option, on which you want to login through ADFS.

(22) Click on Sign In to proceed.

(23) Enter your valid ID & Password to login successfully.

(24) You logged in successfully. Select your project on which you wish to work.

Configure SAML sign-in for OpKey

Login to your OpKey portal using an admin user and navigate to the OpKey admin panel. Go to Single Sign-On > Click Add > and enter the following fields:
- Identity Provider: Select “ADFS” from the drop-down.
- IdP Entity ID: Identity Provider Issuer from Okta, specified earlier.
- Single Sign-On Service: Identity Provider Single Sign-On URL from Okta, specified earlier.
- IdP Certificate: X.509 Public Certificate file you copied from Okta earlier.

Getting started with SSO feature in OpKey

Login to OpKey Web using valid credentials.
Navigate to the Admin Console & select the Single Sign-On tab. Configure the Single-On page opens.
From Single Sign-On page, you need to add and configure Identity Provider.

Click on Add button to add an Identity Provider.
Select Identity Provider (as Okta from the list) & enter IdP Issuer, Display Name, and IdP Single Sign-On URL and then click on Add. You can check Verify Signature checkbox, if required.
- Identity Provider: Select “ADFS” from the drop-down.
- IdP Entity ID: Identity Provider Issuer from ADFS, specified earlier.
- Single Sign-On Service: Identity Provider Single Sign-On URL from Okta, specified earlier.

- You can check the Verify Signature checkbox and enter the corresponding certificate.

- You can also enable encryption by checking Enable Encryption checkbox, as shown in the above screenshot.
Once the Identity Provider (ADFS) has been added successfully, you can view it here.

Further, you can modify and delete it, as required.
Click on Modify Single Sign-On button to modify it. Fill all required fields (Identity Provider, IdP Issuer, Display Name, IdP Single Sign-On URL and Certificate to Validate Signature) and click on Modify.

Once the settings are saved, another option “Allow OpKey Login To” gets enabled which will allow admin to enforce a login type for their users by choosing either of the 3 options as “OpKey Users Only”, “Single Sign-On, “Both OpKey and SSO Users”. So, according to the option selected, OpKey will allow the user to login. In case, user has configured the SSO service, then it is a good option to select the third option i.e. “Both OpKey and SSO Users”.
Further, you need to create Group(s) on Okta & add people to the Group(s) from Group Management as described below:

Group Management

Group Management under Admin Console of OpKey allows you to manage groups of users. Here you can view the list of existing Groups along with details alike Service Provider, Name, Projects, OpKey Admin privileges & Actions. You can edit & delete existing groups as per requirement but you should have Admin privileges to do that.

Navigate to the Group Management tab under the Admin Console in OpKey.

Click on Add Group button. Add Groups page opens.
Select & fill all required fields & click on Add to create a new Group. You can mark OpKey Admin checkbox to provide Admin privileges to the Group.

Here, you can view that a new Group has been created successfully. People belonging to this Group can now work the assigned OpKey project(s) while logging through ADFS SSO.

Now, people belonging to the added Group(s) can login to the OpKey Web using the ADFS SSO feature.

Open your ADFS URL on the web browser.
Select your site from Sign into one of the following sites option, on which you want to login through ADFS.
Click on Sign In to proceed.

Enter your valid ID & Password to login successfully.

You logged in successfully. Select your project on which you wish to work.