Server admin

SAML single sign-on.

With SAML, people sign in to Farwing with the login your company already uses. Farwing is the service provider: the app that trusts your company's login system, called the identity provider. This page covers Okta, Microsoft Entra ID, Google Workspace and ADFS.

Plan: SAML single sign-on needs a Business license or higher. It sits next to the OpenID Connect sign-in and LDAP and Active Directory, and the sign-in page shows a button for each method you turn on. If a server drops to Free mode, sign-ins that already work keep working. They count toward the 5 active users that Free mode allows.

Before you start

Set your server's address first. The values you give your identity provider contain it. Admin → Network sets it. If you change the address later, update the identity provider too.
Check your local administrator. Make sure at least one administrator signs in with a password and an authenticator app. It is your way back in. See If single sign-on stops working.
Keep an administrator session open in one browser while you test in another, so a mistake never locks you out.

Farwing's values

Open Admin → Single sign-on and choose SAML. Farwing shows these values for you to give to your identity provider. You cannot edit them.

Value	Also called	Use
Entity ID	Audience, Audience URI, Identifier, Relying party identifier	Tells the identity provider which app the sign-in is for.
Assertion Consumer Service URL	ACS URL, Reply URL, Single sign-on URL, SAML 2.0 SSO service URL	Where the identity provider sends the signed-in person.
Metadata URL	Federation metadata address	One address that holds the two values above and Farwing's certificate. Use it when your identity provider can import metadata from a URL.
Certificate	Encryption certificate	Needed only if you turn on encrypted assertions.

Your identity provider gives you its own metadata in return. In Farwing, enter its metadata URL, or upload its metadata file. Farwing reads the sign-in address and the signing certificates from it.

Settings in Farwing

Setting	What it does	Default
Signed responses	Farwing requires the response or the assertion to be signed by your identity provider. An unsigned response, or one that was changed, is refused.	Required
Encrypted assertions	Farwing accepts assertions encrypted with its certificate. Give the certificate to your identity provider and switch encryption on there.	Optional
Sign-in from your company's portal	Lets people start from the identity provider's app page, which is called identity-provider-initiated sign-in. By default a sign-in must start from Farwing.	Off
Single logout	Signing out of Farwing signs the person out of the identity provider too.	Off

Attributes and groups

Your identity provider sends facts about the person as attributes. Tell Farwing the name of each attribute you send:

Attribute	Used for	Needed
Email	The person's Farwing account.	Required
Display name	The name shown in the portal.	Optional
Groups	The person's groups at your company.	Optional

Group mapping turns your company's groups into Farwing groups. Add one row for each: the company group on one side and the Farwing group on the other. Farwing creates a user the first time that person signs in, and updates their groups at every sign-in.

Okta

In the Okta Admin Console, open Applications → Applications and choose Create App Integration.
Choose SAML 2.0 and choose Next.
On General Settings, enter the App name Farwing and choose Next.
On Configure SAML, fill in:
- Single sign-on URL: Farwing's Assertion Consumer Service URL. Keep Use this for Recipient URL and Destination URL ticked.
- Audience URI (SP Entity ID): Farwing's entity ID.
- Name ID format: EmailAddress.
- Application username: Email.
Under Attribute Statements, add two rows:
- Name email, value user.email.
- Name displayName, value user.displayName.
Under Group Attribute Statements, add a row with name groups. Set the filter to Starts with and a prefix your Farwing groups share, such as Farwing-. To send every group, choose Matches regex and enter .*.
Choose Show Advanced Settings. Keep Response and Assertion Signature set to Signed. These are the defaults. To use encrypted assertions, set Assertion Encryption to Encrypted and upload Farwing's certificate.
Choose Next, then Finish.
Open the new app's Assignments tab. Choose Assign and add the people or groups who may use Farwing.
Open the Sign On tab and copy the Metadata URL.
In Farwing, open Admin → Single sign-on, choose SAML, paste the metadata URL, and set the attribute names to email, displayName and groups. Add your group mapping and save.
Open Farwing's sign-in page in a private window and choose the SAML button to test.

Microsoft Entra ID

In the Microsoft Entra admin center, open Entra ID → Enterprise apps and choose New application.
Choose Create your own application. Enter the name Farwing, choose Integrate any other application you don't find in the gallery (Non-gallery), and choose Create.
In the new app, open Single sign-on and choose SAML.
In Basic SAML Configuration, choose Edit and fill in:
- Identifier (Entity ID): Farwing's entity ID.
- Reply URL (Assertion Consumer Service URL): Farwing's Assertion Consumer Service URL.
Choose Save.
In Attributes & Claims, choose Edit.
- The email claim is already there. Its name is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress and its value is user.mail.
- Choose Add new claim. Name it displayName and set the source attribute to user.displayname.
- Choose Add a group claim. Choose Groups assigned to the application and Save. The claim is named http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. By default Entra sends each group's object ID, so you map groups by that ID in Farwing. The source attribute list offers other choices.
In SAML Certificates, keep the signing option at Sign SAML assertion, or choose Sign SAML response and assertion. Farwing accepts either. To use encrypted assertions, open the app's Token encryption page and import Farwing's certificate.
In SAML Certificates, copy the App Federation Metadata Url.
Open Users and groups, choose Add user/group, and assign the people or groups who may use Farwing.
In Farwing, open Admin → Single sign-on, choose SAML, paste the metadata URL, and set the attribute names to the email claim, displayName and the groups claim above. Add your group mapping and save.
Open Farwing's sign-in page in a private window and choose the SAML button to test.

Google Workspace

In the Google Admin console, open Apps → Web and mobile apps. Choose Add app, then Add custom SAML app.
On App details, enter the name Farwing and choose Continue.
On Google Identity Provider details, choose Download Metadata and keep the file. Choose Continue. Google does not offer a metadata URL, so you will upload this file to Farwing.
On Service provider details, fill in:
- ACS URL: Farwing's Assertion Consumer Service URL.
- Entity ID: Farwing's entity ID.
- Name ID format: EMAIL.
- Name ID: Basic Information > Primary email.
- Tick Signed response.
Choose Continue.
On Attribute mapping:
- Choose Add mapping. Map Basic Information > Primary email to the app attribute email.
- Under Group membership, search for the groups to send and map them to the app attribute groups.
- Google has no single full-name attribute, so leave display name unmapped.
Choose Finish.
On the new app's page, choose User access. Turn the service On for everyone or for the organizational units and groups that may use Farwing, and choose Save. Google can take a while to apply the change.
In Farwing, open Admin → Single sign-on, choose SAML, upload the metadata file you downloaded, and set the attribute names to email and groups. Add your group mapping, using each group's name as Google lists it, and save.
Open Farwing's sign-in page in a private window and choose the SAML button to test.

ADFS

On the AD FS server, open AD FS Management. Open Relying Party Trusts and choose Add Relying Party Trust.
On Welcome, choose Claims aware and choose Start.
On Select Data Source, choose Import data about the relying party published online or on a local network. Enter Farwing's metadata URL as the Federation metadata address. The AD FS server must be able to reach Farwing and trust its certificate. If it cannot, save Farwing's metadata as a file and choose Import data about the relying party from a file.
On Specify Display Name, enter Farwing.
On Choose Access Control Policy, choose Permit everyone, or the policy your company uses.
Choose Next through the summary and choose Close. Leave Configure claims issuance policy for this application ticked.
In Edit Claim Issuance Policy, choose Add Rule. Choose the template Send LDAP Attributes as Claims and choose Next. Name the rule Farwing attributes, set the Attribute store to Active Directory, and add three mappings:
- E-Mail-Addresses to the outgoing claim type E-Mail Address (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress).
- Display-Name to Name (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name).
- Token-Groups - Unqualified Names to Group (http://schemas.xmlsoap.org/claims/Group).
Choose Finish.
Choose Add Rule again. Choose the template Transform an Incoming Claim. Set the incoming claim type to E-Mail Address, the outgoing claim type to Name ID, and the outgoing name ID format to Email. Choose Pass through all claim values and Finish. Choose OK to save the policy.
AD FS signs the assertion by default, which Farwing accepts. To sign the whole response as well, run this on the AD FS server in PowerShell:
```
Set-AdfsRelyingPartyTrust -TargetName "Farwing" -SamlResponseSignature MessageAndAssertion
```
To use encrypted assertions, open the trust's Properties, choose the Encryption tab, and browse to Farwing's certificate.
Your AD FS metadata is at https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml, with your own host name. In Farwing, open Admin → Single sign-on, choose SAML, and enter that URL. Set the attribute names to the three claim types above, add your group mapping and save.
Open Farwing's sign-in page in a private window and choose the SAML button to test.

If single sign-on stops working

The local administrator account always works. Single sign-on, LDAP and OpenID Connect can all fail, for example because the identity provider is down or a certificate changed, and an administrator can still sign in with a password.

The local administrator must have a password and an authenticator app. Farwing shows a warning while it has no authenticator. Set one up before you turn single sign-on on.

To get back in:

Open your Farwing server's normal sign-in page.
Type the local administrator's email and password into the form, and choose Sign in. Do not use the button that starts single sign-on.
Enter the 6-digit code from the authenticator app. If you no longer have the app, choose Use a recovery code instead and enter a code you saved when you set it up. Or ask another administrator to reset your second factor.
Open Admin → Single sign-on. Correct the setting, or turn SAML off, and save.
Test in a private window before you close the administrator session.

Common causes are an identity provider certificate that was replaced (load its metadata again), a changed server address (update the identity provider with the new values), and a server clock that is wrong.

Admin → Audit records every single sign-on sign-in, every failure and every change to these settings. The failure entries help you find the cause.