SSO configuration with AD FS

danger

Before configuring SSO, make sure that the APP_URL parameter in config.env matches the current Passwork domain, example — APP_URL=https://passwork.example.com

The following server names are used as examples:

• Provider (IDP) — ad-fs.passwork.local
• Passwork server (SP) — passwork.example.com

Adding a Relying Party Trust

Open — Server Manager → Tools → AD FS Management → Relying Party Trusts → Actions:

Perform the steps in the — Add Relying Party Trust Wizard:

1. Claims aware;
2. Enter data about the relying party manually;
3. Fill in the Display name (example: passwork-sp);
4. Skip the step — Configure Certificate, click Next;
5. At the Configure URL step:
   1. Enable support for the SAML 2.0 WebSSO protocol;
   2. Copy from Passwork in — Settings and Users → SSO Settings — the Reply URL;
   3. Paste into Relying party SAML 2.0 SSO service URL — https://passwork.example.com/api/v1/sso/acs
6. At the Configure Identifiers step:
   1. Copy from Passwork in — Settings and Users → SSO Settings — the Identifier;
   2. Paste into Relying party trust identifier — https://passwork.example.com/api/v1/sso/metadata
7. Skip the step — Choose Access Control Policy, click Next;
8. Skip the step — Ready to Add Trust, click Next;

Example output of the created trust in PowerShell

PowerShell

Get-ADFSRelyingPartyTrust -Name "passwork-sp" # Command to display

AllowedAuthenticationClassReferences : {}
EncryptionCertificateRevocationCheck : CheckChainExcludeRoot
PublishedThroughProxy                : False
SigningCertificateRevocationCheck    : CheckChainExcludeRoot
WSFedEndpoint                        :
AdditionalWSFedEndpoint              : {}
ClaimsProviderName                   : {}
ClaimsAccepted                       : {}
EncryptClaims                        : True
Enabled                              : True
EncryptionCertificate                :
Identifier                           : {https://passwork.example.com/api/v1/sso/metadata}
NotBeforeSkew                        : 0
EnableJWT                            : False
AlwaysRequireAuthentication          : False
Notes                                :
OrganizationInfo                     :
ObjectIdentifier                     : 03363cb7-5eef-ef11-b8b3-000c2993a976
ProxyEndpointMappings                : {}
ProxyTrustedEndpoints                : {}
ProtocolProfile                      : WsFed-SAML
RequestSigningCertificate            : {}
EncryptedNameIdRequired              : False
SignedSamlRequestsRequired           : False
SamlEndpoints                        : {Microsoft.IdentityServer.Management.Resources.SamlEndpoint}
SamlResponseSignature                : AssertionOnly
SignatureAlgorithm                   : http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
TokenLifetime                        : 0
AllowedClientTypes                   : Public, Confidential
IssueOAuthRefreshTokensTo            : AllDevices
RefreshTokenProtectionEnabled        : True
RequestMFAFromClaimsProviders        : False
ScopeGroupId                         :
ScopeGroupIdentifier                 :
DeviceAuthenticationMethod           :
Name                                 : passwork-sp
AutoUpdateEnabled                    : False
MonitoringEnabled                    : False
MetadataUrl                          :
ConflictWithPublishedPolicy          : False
IssuanceAuthorizationRules           :
IssuanceTransformRules               :
DelegationAuthorizationRules         :
LastPublishedPolicyCheckSuccessful   :
LastUpdateTime                       : 01.01.1900 5:00:00
LastMonitoredTime                    : 01.01.1900 5:00:00
ImpersonationAuthorizationRules      :
AdditionalAuthenticationRules        :
AccessControlPolicyName              : Permit everyone
AccessControlPolicyParameters        :
ResultantPolicy                      : RequireFreshAuthentication:False
                                       IssuanceAuthorizationRules:
                                       {
                                         Permit everyone
                                       }
                                       
Get-ADFSRelyingPartyTrust -Name "passwork-sp" | Select-Object -ExpandProperty SamlEndpoints # Command to display

Binding          : POST
BindingUri       : urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
Index            : 0
IsDefault        : False
Location         : https://passwork.example.com/api/v1/sso/acs
Protocol         : SAMLAssertionConsumer
ResponseLocation :                                       

Open the Properties of the created Relying Party Trust:

In Properties, go to Endpoints and perform the following actions:

1. Add SAML;
2. Endpoint type — SAML Logout Endpoint;
3. Binding — Redirect;
4. Copy from Passwork in — Settings and Users → SSO Settings — the Logout URL;
5. Paste into Trusted URL — https://passwork.example.com/api/v1/sso/sls
6. Apply changes and close Properties.

Configuring request processing rules from SP (Passwork) in IDP (AD FS)

danger

Depending on the desired user login format in Passwork, you can configure processing rules so that the user format can be one of the following:

• username
• [email protected]

Please choose the required user login format in Passwork and configure accordingly.

In Relying Party Trusts, select the created trust (passwork-sp) and open — Edit Claim Issuance Policy:

Configuring processing rules for [email protected] format

Perform the following actions:

1. Add Rule;
2. Send LDAP Attributes as Claims;
3. Claim rule name — AttributeStatement;
4. Attribute store — Active Directory;
5. LDAP Attribute — User-Principal-Name;
6. Outgoing claim type — UPN.

Perform the following actions:

1. Add Rule;
2. Transform an Incoming Claim;
3. Claim rule name — Name ID Format;
4. Incoming claim type — UPN;
5. Outgoing claim type — Name ID;
6. Outgoing name ID format — Transient Identifier.

Configuring processing rules for username format

Perform the following actions:

1. Add Rule;
2. Send LDAP Attributes as Claims;
3. Claim rule name — AttributeStatement;
4. Attribute store — Active Directory;
5. LDAP Attribute — SAM-Account-Name;
6. Outgoing claim type — E-Mail Address;

Perform the following actions:

1. Add Rule;
2. Transform an Incoming Claim;
3. Claim rule name — Name ID Format;
4. Incoming claim type — E-Mail Address;
5. Outgoing claim type — Name ID;
6. Outgoing name ID format — Transient Identifier.

Configuring additional attribute processing rules for passing to SP

Edit the created rule named AttributeStatement:

1. Pass to SP (Passwork) the Display-Name attribute:
   1. LDAP Attribute — Display-Name;
   2. Outgoing claim type — enter displayName;
2. Pass to SP (Passwork) the E-mail-Address attribute:
   1. LDAP Attribute — E-Mail-Addresses;
   2. Outgoing claim type — enter emailAddress;

Configuring and filling Single Sign-On (SSO) parameters in Passwork

Filling in the "User Attributes" Values

Log in to the Passwork web interface, go to — Settings and Users → SSO Settings and fill in the attribute mappings:

• Email attribute — emailAddress;
• Full name attribute — displayName.

Filling in the "Identity Provider → Passwork" Values

Open AD FS Management → select the AD FS directory → Edit Federation Service Properties:

Copy the address — Federation Service Identifier → http://ad-fs.passwork.local/adfs/services/trust:

Open — Settings and Users → SSO Settings and fill in the values:

• Identifier (Entity ID) — http://ad-fs.passwork.local/adfs/services/trust
• Login URL — https://ad-fs.passwork.local/adfs/ls
• Logout URL — https://ad-fs.passwork.local/adfs/ls/?wa=wsignout1.0

Filling in the "Certificate" Value

Open and export the generated SSL certificate in base64 format — AD FS Management → Service → Certificates → Token-signing:

Open the exported SSL certificate with Notepad, copy it and paste into the corresponding field — Settings and Users → SSO Settings.

Example of exported key in base64 format

base64

-----BEGIN CERTIFICATE-----
MIIE5DCCAsygAwIBAgIQM/9SlLjzJLBHaSgQVsIEPzANBgkqhkiG9w0BAQsFADAu
MSwwKgYDVQQDEyNBREZTIFNpZ25pbmcgLSBhZC1mcy5wYXNzd29yay5sb2NhbDAe
Fw0yNTAyMTkyMDA3MjFaFw0yNjAyMTkyMDA3MjFaMC4xLDAqBgNVBAMTI0FERlMg
U2lnbmluZyAtIGFkLWZzLnBhc3N3b3JrLmxvY2FsMIICIjANBgkqhkiG9w0BAQEF
AAOCAg8AMIICCgKCAgEAs6isogLhwqdncR1tYqKgS+Dwmi3DOIMfDpQNgaD/S5Vd
FngFsZ048zfYqJAn9Ypnu8UCTftoKJ2BQzRPoqaT2lpaAivyTDLKBMmbaAyOHoQH
RAd6NQazUYcbW2vMWwA4sa8hTDwwwZPOFhx3AR5EbW4IQo0sHWHOYCIWmH0td9+4
Lqiy7VkHT3fcUCuDL+kopjnsvdJLvbpg7ZPFkYLgy/ANP9+90yt/L1/Mj682bV3b
HgaPbAOzaG7qS6pA94wPmKYLnNf2C89vSfBaA+KjfWjhK5YMPbWLUxolNX7zz6bx
BQKdU/W7pTQIIIffy0rLNwWyaQbKKh77C9OKWLE3k54OhNAyJHXF332CK7psPSVT
fRDqagYGZQF/EhPQG7kMPpr6IiZ76v9FmZz59ruYaLA9f0YYK2NpiLdY1EHLdm19
H+72T/ZFEOLKExr+BbEOcQAlnqGXSs0YdrWTwMEBCqnrPiS4153298VEqKto1sUz
hqnBookmLgUymqApN50KIffezRK/ghfoxBY16EzlYAyVyWqaAB5WEAbCgdB2p9RN
KZHeYz3iB/cQzps1DYsZhZJ9SLS0yr8aQgYMl0PyKS7ajPR9GlGSKKz/7Q6POOtY
jz7qLcBgApacUJfOqUr2OcPzU/TsvRyHhPNzW41hIEjGWBVJ6WlpUFQYJxp5rxkC
AwEAATANBgkqhkiG9w0BAQsFAAOCAgEAbKOjd7u1qnVfL4HsVNSCSUTqXI4knvxI
NKQxZWCpkdCxPzpJJdtMPsGukZQAblEcgQPX+v94F32BA2bk8cgp08ra2OrXEXR7r
XCCm3BvUAsI6nmbzKHPm6y/3awadOu59k8qE1c+DRSrHHM9927Z4QWMKYLfKEQL4
4WBYbw/jgqs7HqMbxrdfCtNdQzGKcE+sVaT9OnDp86TopHbsndRUyXqfqkB/LSbq
cstg/cC1b9xJ+FI3xUXEl/33e9/p8ovFko5slW5kU6qET9cg6GA0OreIb+8FbbiV
LOll4aIsn44/wQ6mu3biw77l1TpoUQpf11G9fpuOV10WRttOtk4IsryMhsbrGa/R
RZMbWH2MgkLs1VlcigrUE6kMIkU743d8oyLQb7N4+O+h56YLIuWWXUMM1FNNCIov
tVutUBpSO6OgTUo5tcD9uqaD5R1+rf5A68yUslMgU+4mE9hdY/143bZMDPexKcUt
jfZOI9v4ppmoFgeWZDYMtxU40OkYZh/grnxw9aoZEPLfr8Vnf+LhGvhEFWKvvwdv
J7n49c1WxZxK7rDaSwKeydgLC1bySFQoiYkOucfO+NcdBi6R44cXBrWk1EESLuCq
X2LLIS2NoKg8pX2BPqPcTuZGclEivpg0rrovksNj3L3BRtFO3jWooqxxOfVUbk8h
uFmSLzpAW1I=
-----END CERTIFICATE-----

Filling in the "Additional Settings" Value

Paste the following content in JSON format:

json

{
	"sp": {
		"entityId": "https://passwork.example.com/api/v1/sso/metadata",
		"assertionConsumerService": {
			"url": "https://passwork.example.com/api/v1/sso/acs"
		},
		"singleLogoutService": {
			"url": "https://passwork.example.com/api/v1/sso/sls"
		},
		"NameIDFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
	}
}

danger

Replace the domain passwork.example.com in the URLs with your Passwork server domain.

Open the login window in the Passwork web interface and log in via SSO to verify the correct configuration: