Skip to main content

Initiate Single Sign-On

Author: Mark Rickard Updated

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). SAML enables users to sign in once and access multiple applications without logging in again.

In most cases, your company serves as the IdP and delegates the SP role to Fuel Cycle. Your users log in through your IdP system—for example, Okta—and then access Fuel Cycle without signing in again. Fuel Cycle can also act as the IdP, delegating the SP role to a third-party platform such as Alchemer or Qualtrics.

Fuel Cycle supports SAML 2.0 SSO. To enable it, contact your Fuel Cycle representative.

These instructions assume your company's IT personnel handles the metadata exchange.

Preliminary requirements

Fuel Cycle can set up SSO for moderators, community members, or both. Specify your preference with your Fuel Cycle representative.

Before setup begins, confirm:

  • Your company assumes the role of identity provider (IdP) and delegates the role of service provider (SP) to Fuel Cycle.
  • Your company has a SAML 2.0 SSO login system configured for the IdP role.

How to set up

  1. Fuel Cycle provides you with SP metadata.
  2. Your company adds the SP metadata to your SAML 2.0 SSO system.
  3. Your company provides Fuel Cycle with your IdP metadata and signing certificate (if applicable).
  4. Fuel Cycle adds your IdP metadata and signing certificate to your community backend.

SAML cert content.png

SSO options

By default, SSO setup enables moderator login via SSO while still allowing username and password login. Two additional options are available on request:

  • SSO Limited — Restricts moderator login to SSO only. Moderators cannot log in with a username and password.
  • SSO Provisioning — Enables Just-in-Time creation of moderator accounts. Fuel Cycle creates a moderator account automatically when a user authenticates via SSO for the first time.

Contact your Fuel Cycle representative to enable either option.

Attribute requirements

Your SAML response must include the following attributes.

Required:

EmailAddress, email, mail, or a NameID / principal name containing the user's email address. This value is case- and space-sensitive and must exactly match the email address on the Fuel Cycle account.

Optional (required only if SSO Provisioning is enabled):

  • FirstName or first name
  • LastName or last name

Test your SSO integration

Once setup is complete, test the integration before rolling it out. For accurate results, test in an incognito or private browser window.

The tester must meet both of the following conditions:

  • The tester has an existing moderator account in the Fuel Cycle community.
  • The email address on the moderator account exactly matches the email stored in your SSO system. A mismatch will cause the SAML handshake to fail.

Troubleshooting

If a user cannot log in via SSO, check the following:

  1. Moderator account — Confirm the user has an existing moderator account in the Fuel Cycle community.
  2. Email match — Confirm the email on the moderator account exactly matches the email in your SAML authentication system.
  3. SSO access — Check with your internal SSO administrator to confirm the user has been granted access to the Fuel Cycle application in your SSO system.

If the issue persists, contact Fuel Cycle support with a screenshot of the error message and the user's email address.

Certificate expiry

If your signing certificate expires, provide Fuel Cycle with both a new signing certificate and updated IdP metadata. When your certificate updates, your IdP metadata also updates — Fuel Cycle requires both to restore the integration.

Sending email addresses in the SAML response

Every SAML 2.0 SSO login must include the user's email address associated with their community registration. Send it as a saml:Attribute with the attribute name Email, EmailAddress, email, mail, or in the NameID element. The value must exactly match the email address on the Fuel Cycle account.

For example:

 
xml
<saml2:Subject>
  <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
    pgunasekaran@fuelcycle.com
  </saml2:NameID>
  <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <saml2:SubjectConfirmationData
      NotOnOrAfter="2022-09-13T23:03:05.312Z"
      Recipient="https://fcprd.fuelcyclestage.com/saml/SSO/alias/xxx"/>
  </saml2:SubjectConfirmation>
</saml2:Subject>

If SSO Provisioning is enabled, include first and last name attributes in the SAML response:

 
xml
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
  <saml2:Attribute Name="first name"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">padmapriya</saml2:AttributeValue>
  </saml2:Attribute>
  <saml2:Attribute Name="last name"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">gunasekaran</saml2:AttributeValue>
  </saml2:Attribute>
  <saml2:Attribute Name="email"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">pgunasekaran@fuelcycle.com</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>
Was this article helpful?