SAML apps

Let your users sign in to SAML 2.0 apps, such as Grafana, AWS IAM Identity Center or Google Workspace, with their Fob account. Fob is the identity provider (IdP) and the app is the service provider (SP).

Permission

Needs Manage apps.

SAML apps use assignments, sign-on policies, Email address sent and the apps page just like OpenID Connect apps.

Add a SAML app

1. Open Apps > Apps, choose Add app, name it and choose SAML app.

2. If the service provider gives you metadata XML, paste it under Service provider metadata and choose Read metadata. Otherwise, enter its Single sign-on URL (also called the ACS URL) and Audience (its entity ID).

3. Choose Add app.

4. Copy Fob's details from Fob's details on the app's General tab into the service provider. Most service providers only need the metadata URL.

   Detail	Example
   Metadata URL	https://acme.fobauth.com/saml/metadata
   Sign-on URL	https://acme.fobauth.com/saml/sso
   Issuer (entity ID)	https://acme.fobauth.com/saml/metadata
   Certificate	Download certificate gives it as PEM. The SHA-256 fingerprint is shown too.

5. Sign in to the service provider to test it. You should be sent to Fob's sign-in page and back.

The app is open to everyone in your organization. To limit it to some groups, see Assignments.

Custom domains

If you have a custom domain, the sign-on URL uses it. The metadata URL and issuer always stay on fobauth.com, so they never change.

Send attributes

Attributes tell the service provider about the user, such as their name and groups. Edit them under Attributes in the Service provider section of the app's General tab, then choose Save. A new app sends email, firstName, lastName and name.

Value	What's sent
Email	The address chosen by the app's Email address sent setting
First name, Last name	The user's first or last name. If they don't have one, Fob splits their full name at the first space.
Full name	The user's name
User ID	Fob's ID for the user
Groups	One value per group the user is in
A profile attribute	The user's value, for profile attributes that are sent to apps and aren't sensitive. Lists send one value per item.

Each attribute also has a Format (Basic, URI or Unspecified), sent as its NameFormat. An app can have up to 50 attributes.

For example, to give Grafana the user's groups, add an attribute named groups with the value Groups, then map it in Grafana:

[auth.saml]
assertion_attribute_email = email
assertion_attribute_name = name
assertion_attribute_groups = groups

Choose the Name ID

Name ID in the Service provider section sets the subject of the assertion, which many service providers use to match accounts.

Option	Sends
Email address (default)	The user's email, as emailAddress
Persistent ID	Fob's ID for the user, which never changes
Unspecified	The user's email, as unspecified

Use Persistent ID if the service provider supports it. If it matches accounts on the email instead, a user whose email changes ends up with a second account.

Sign in from Fob

A SAML app with no launch URL gets a tile on the apps page that starts sign-in from Fob's side (IdP-initiated). To choose where the service provider sends users afterwards, set Default relay state in the Service provider section.

Signing

Fob signs both the response and the assertion by default. You can turn off either Sign the response or Sign the assertion, but not both. Assertions aren't encrypted.

Your organization has one SAML signing certificate (RSA 2048-bit, valid for ten years), shared by all its SAML apps. It's separate from the signing keys used for OpenID Connect.

Endpoints

Endpoint	Method	Path
Metadata, also the IdP entity ID	GET	/saml/metadata
Single sign-on	GET (HTTP-Redirect), POST (HTTP-POST)	/saml/sso
IdP-initiated sign-in	GET	/saml/apps/{app id}/start

Protocol details

Requests

• Fob finds the app by the AuthnRequest's Issuer. AuthnRequest signatures aren't checked.
• If the request includes an AssertionConsumerServiceURL, it must exactly match the app's registered single sign-on URL. Fob only ever posts responses to the registered URL.
• ForceAuthn="true" makes the user sign in again. IsPassive="true" returns a NoPassive status instead of showing a sign-in page.
• If Fob can't trust the request, or the user isn't allowed in, it shows its own error page instead of posting to the service provider.

Responses

Responses are sent by HTTP-POST to the app's single sign-on URL.

Part	Value
Destination, Recipient	The app's single sign-on URL
Issuer	Fob's entity ID
Audience	The app's audience
NotBefore, NotOnOrAfter	One minute before, and five minutes after, the response is created
Signature	RSA-SHA256, exclusive canonicalization

AuthnContextClassRef says how the user signed in:

Sign-in	AuthnContextClassRef
Password alone	urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
Passkey, or password and second factor (including an identity provider that reported MFA)	https://refeds.org/profile/mfa
Anything else, including impersonation	urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

During an impersonation, responses also carry a fob_impersonator attribute with the admin's email. See Impersonation.