How to set up Custom Single Sign-On (SSO) with Affinity

What is SSO?

Single Sign-On is an authentication method that allows users to use one set of login credentials to log into multiple applications.

Note: Custom SSO is only available for Affinity customers on the Enterprise tier.

How to set up SSO with SAML 2.0

1. Affinity needs the following information from your IT/Admin:
   • Audience URI/Client/SP Entity ID (e.g. affinity)
   • Name ID Format set to Email Address
   • Your Identity Provider (IdP) - (e.g. Okta, Azure, etc.)
   • Your Metadata URL. (This will contain the cert)
   • (Optional) Set relay state to IDP-INITIATED-FLOW. This is only necessary if you wish to configure a seamless IDP flow.
2. Redirect (reply) URIs for the Affinity Web Application. Also known as Single sign on URL.
   
   • https://[subdomain].affinity.co/auth/sso/saml-callback​ (login)
   • https://[subdomain].affinity.co/sso/callback (needed for mobile login)
   • https://[subdomain]​.affinity.co/logout​ (logout)
3. Setting up data sync; one of the three would need to be configured.
   • If your team is on Google and has a different SSO provider, your IT must set up a domain-wide delegation.
   • If your team is on Azure (Office365), then the Microsoft Graph Client Credential flow is required to sync data.
   • If your team is on Microsoft On-Premise (or Hosted) Exchange, then an Impersonation Service Account is required to sync data. 
     • Here are the necessary pieces of information that you/your team must send over to support@affinity.co to set up your Impersonation Service Account and leverage Affinity:
       • Mail server EWS URL
       • Impersonation Email Address
       • Impersonation Username (not always required)
       • Impersonation Password

How to set up SSO with Open ID

Using OpenID, you will most likely need to set up two apps - one for web (see Step 2) and one for mobile (see Step 3).

1. Affinity needs the following information from your IT/Admin:
   
   • Audience URI/Client/SP Entity ID (eg. affinity)
   • Client Secret
   • Name ID Format set to Email Address
   • Identity Provider (IdP) - (e.g. Okta, Azure, etc.)
   • OIDC Discovery Endpoint
   • Mobile Client ID 
   • Mobile Client Secret
   • (Optional) Set relay state to IDP-INITIATED-FLOW. This is only necessary if you wish to configure a seamless IDP flow.
2. Redirect (reply) URIs for the Affinity Web Application (for web)
   
   • Sign in: https://[subdomain].affinity.co/auth/sso/openid-callback​
   • Sign out: https://[subdomain]​.affinity.co/logout​
3. Mobile Login/Logout redirect URIs (for mobile)
   
   • AffinitySSOLogin://login
   • AffinitySSOLogin://logout
4. Setting up data sync:
   • If your team is on Google and has a different SSO provider, your IT must set up a domain-wide delegation.
   • If your team is on Azure (Office365), then the Microsoft Graph Client Credential flow is required to sync data.
   • If your team is on Microsoft On-Premise (or Hosted) Exchange, then an Impersonation Service Account is required to sync data. 
     • Here are the necessary pieces of information that you/your team must send over to support@affinity.co to set up your Impersonation Service Account and leverage Affinity:
       • Mail server EWS URL
       • Impersonation Email Address
       • Impersonation Username (not always required)
       • Impersonation Password

Frequently Asked Questions

What type of SSO does Affinity support?

• Affinity currently supports SAML 2.0 or OpenID Connect as an authentication method. 

Does Affinity support Service Provider initiated(Web Browser) SSO?

• Yes. Set relay state to IDP-INITIATED-FLOW.

What claims (attribute) does Affinity require in the callback request?

• We only require the user’s email address.
  
  

What’s the most secure hash algorithm that Affinity accepts?

• SHA256.
  
  

Does Affinity require token encryption?

• We do not require token encryption. We won’t make any additional requests after initial authentication, so this shouldn’t be necessary.
  
  

Does Affinity require Relaying Party-Initiated(RP) Sign-On?

• No. Affinity is a cloud application accessible over the public internet; most of our users access the application directly by our URL on their browser.
  
  

Does Affinity require Relay State support?

• No.
  
  

Have you enabled your site to automatically update your federated metadata information?

• Yes. We periodically refresh the metadata stored for your organization from your metadata URL. For example, if your public key changes, Affinity will detect the change and continue to validate signatures accordingly.