SSO Configuring OAUTH

Helpy supports Omniauth login meaning you can allow your support users to sign in with a single click via any Omniauth provider. Setting this up varies per provider, but the set up within Helpy involves adding some configuration to the settings.yml file and restarting your server.

Each provider will supply you with two things- an ID and a SECRET. Take these and add them to your settings file:

omniauth:
  providers:
    github:
      id: e059de7a11e01b25d48e
      secret: 3083f75f2aa69a69ec8e0f14f3211dde4114d93c
#    twitter:
#      id: 
#      secret: 
#    google_oauth2:
#      id: 
#      secret: 

In this example, I have decided to allow logins through Github. I uncommented the lines in my settings.yml file for Github and provided the id and secret provided by Github (don't worry, these are not real keys!). You should not share your keys for any reason!

Provider Setup

To get the ID and Secret referenced above, you will need to sign up with each unique provider and provide some basic information about your app. Each provider varies slightly. As an example, we will take a look at Github:

The most important thing to complete here is the "Authorization callback URL". This is where the user will be redirected to after they have been successfully authorized. Go ahead and enter the main URL for your support site.

http://support.yourdomain.com/

SAML Setup

Helpy also supports SAML through the omniauth-saml plugin. In order to make the integration, you will need to register some data from the IdP metadata that should be provided by the IdP Administrator. In addition, the IdP need to register the Helpy SP metadata available on the URL: <helpy_base_url>/users/auth/saml/metadata

omniauth:
  providers:
#    saml: # See more info about the settings at the omniauth-saml repo https://github.com/omniauth/omniauth-saml#options
#      issuer: "<helpy_base_url>/users/auth/saml/metadata" # SP Entity ID, Recommended to set the URL where the SP metadata is published 
#      assertion_consumer_service_url: "<helpy_base_url>/users/auth/saml/callback"  # SP Assertion Consumer Service Endpoint
#      single_logout_service_url: "<helpy_base_url>/users/auth/saml/slo" # SP Single logout Service Endpoint
#      slo_default_relay_state: "<helpy_base_url>"  # Where to redirect the user after login off
#      idp_entity_id: # IdP Enity ID
#      idp_sso_target_url: # IdP Single Sign On Service URL
#      idp_slo_target_url: # IdP Single Logout Service URL
#      idp_cert: # IdP x509 cert
#      name_identifier_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
#      uid_attribute: "User.email" # Attribute that uniquely identifies the user. If unset, the name identifier returned by the IdP is used.
#      attribute_statements: {email: ['User.email'], uid: ['Username'], name: ['User.FirstName'], first_name: ['User.FirstName'], last_name: ['User.LastName']} # Used to map Attribute Names in a SAMLResponse to entries in the OmniAuth info hash

For more info about the available options visit https://github.com/omniauth/omniauth-saml#options