Configuring Authentication for the Console via AD FS – Capsule8

Summary

Configuration steps for managing Console access via Active Directory Federation Services.

Version(s)

Capsule8 Console version 4.4.0+

SAML

Active Directory Federation Services

Create a New Relying Party Trust

Membership in Administrators, or equivalent, on the local computer is the minimum required to complete this procedure. Review details about using the appropriate accounts and group memberships at Local and Domain Default Groups.

In Server Manager, click Tools, and then select AD FS Management.
Under Actions, click Add Relying Party Trust.
On the Welcome page, choose Claims aware and click Start.
On the Select Data Source page, click Enter data about the relying party manually, and then click Next.
On the Specify Display Name page, type a name in Display name, under Notes type a description for this relying party trust, and then click Next.
On the Configure Certificate page, if you have an optional token encryption certificate, click Browse to locate a certificate file, and then click Next.
On the Configure URL page, select Enable support for the SAML 2.0 WebSSO protocol check box. Under Relying party SAML 2.0 SSO service URL, type the Security Assertion Markup Language (SAML) service endpoint URL for this relying party trust, and then click Next.
On the Configure Identifiers page, specify https://capsule8.mycompany.com/sessions/saml/adfs/metadataas an identifier for this relying party. Click Add to add them to the list, and then click Next.
On the Choose Access Control Policy select a policy and click Next. For more information about Access Control Policies, see Access Control Policies in AD FS.
On the Ready to Add Trust page, review the settings, and then click Next to save your relying party trust information.
On the Finish page, click Close. This action automatically displays the Edit Claim Rules dialog box.

Claims Issuance Configuration:

Open AD FS Management Console.
Select the newly created Relying Party Trust.
Click Edit Claim Issuance Policy.
Click Add Rule...
Select Send LDAP Attributes as Claims and click Next
Configure the rule as the following, then click OK
Claim rule name: Outgoing Claims
Attribute store: Active Directory
User-Principal-Name: UPN
E-Mail-Addresses: E-Mail Address
Display-Name:Name
Is-Member-Of-DL: Group
Add another rule for a new claim.
Select Transform an Incoming Claim from the rule template drop-down.
Configure the rule as the following, then click OK
Claim rule name: Send Name Id
Incoming claim type: UPN
Outgoing claim type: Name ID
Outgoing name ID format: Unspecified
Select Pass through all claim values

Configure AD FS Signing Certificate

SAML requires Federation Services to sign requests with your Console's public key for logging users out.

On AD FS Management console, select your Relying Party Trust.
Right click and select Properties.
Click on the Signature tab and click Add..
In the File Explorer, select your Console's Public key.

Setting up the Console's Endpoints

The Console communicates with AD FS through predetermined endpoints.

On AD FS Management console, select your Relying Party Trust.
Right click and select Properties.
Click on the Endpoints tab and click Add..
Click Add SAML
Configure as the following, then click OK.
Endpoint type: SAML Assertion Consumer
Binding: POST
Index: 0
Trusted URL: https://capsule8.mycompany.com/sessions/saml/adfs/acs
Repeat the process for the following endpoint, then click OK.
Endpoint type: SAML Logout
Binding: Redirect
Trusted URL: https://capsule8.mycompany.com/sessions/saml/adfs/slo/request
Response URL: https://capsule8.mycompany.com/sessions/saml/adfs/slo/response

Set required Variables in the Configuration file

After setting up ADFS, set the following variables on the configuration file.


console:
  #...
  auth_saml_adfs_enabled: true
  auth_saml_console_host: 0.0.0.0:80
  auth_saml_local_cert_file_path: /path/to/cert
  auth_saml_insecure_skip_verify: true
  auth_saml_metadata_url: "https://dev-326354.okta.com/app/exkplucpmmntKXezz4x6/sso/saml/metadata"
  tls_cert_path: /path/to/cert
  tls_key_path: /path/to/key
  auth_saml_insecure_skip_verify: true
  auth_saml_local_cert_file_path: /path/to/cert

console.auth_saml_adfs_enabled: needs to be set to either true or false to turn ADFS integration on or off, respectively.
console.auth_saml_console_host: Point to where your Console's API is running, represented as <your-console-host> in the previous steps. By default it's the same value as console.address. This is done so ADFS can resolve your Console's location.

console.auth_saml_local_cert_file_path: should point to the path of your ADFS' PEM (public key in DER format) file.
console.auth_saml_insecure_skip_verify For self-signed certificate this field should be set to True. But we do not recommend using self-signed certificate outside of testing.
console.auth_saml_metadata_url Need to be set to your relying party trust metadata endpoint. It is typically set to https://dev-326354.okta.com/app/exkplucpmmntKXezz4x6/sso/saml/metadata
If you want to override the default self-signed certificate shipped with the console, set the following variable to the corresponding file:
console.tls_cert_path is your existing Console's crt file.
console.tls_key_path is your Console's private key file.
console.auth_saml_insecure_skip_verify is set to False by default and should be set to False.
The certificate in console.auth_saml_local_cert_file_path must be signed by a certificate authority.