Single-Sign-On (SSO) Support

Impact+ supports a service provider (SP-initiated) SSO only. When SSO is configured, users initiate the login process by clicking a program link. This link routes the user to their company login for authentication, bypassing the Bunchball registration and login. After authentication, users can directly access the Impact+ site.

Workflow

Impact+ SSO Flowchart

* The user’s Nitro UserID (gamification ID) and auth mapping must exist before the user can access the site.

General Checklist

Impact+ supports Single Sign-On (SSO) via SAML (Security Assertion Markup Language) and OIDC (OpenID Connect), providing secure and seamless authentication of users.

	Task	Details
	Provide the SSO login button name to Bunchball.	The login button text can be customized for your program, such as "Log in with your [company name] credentials". This cannot be changed after creation.
	Determine if the SSO setup will also include self-registration.	You can allow access via SSO only, or SSO plus self-registration. You must determine your access type before setup begins. This cannot be changed after creation. Email Required - SSO uses email. You can also allow self-registration with email. Email Optional - SSO may or may not use email. No self-registration is allowed.
	Provide a test user for validation.	Provide an SSO test user to allow Bunchball to validate login functionality.
	Configure the user pool domain.	Your system must allow authentication requests from Cognito by adding the user pool domain as an allowed callback. Note: Not all IdPs require setting up allowed callbacks.

OIDC Checklist

The following are required to use OIDC authentication. Bunchball may request additional information as needed.

	Task	Details
	Provide a JSON file that maps OIDC attributes from your environment to Bunchball.	The file must contain the provider's configuration, including all necessary endpoints, tokens, and other metadata. Show me an example Copy { "providerName": "LoginWithAuth0", // The login button will have this label "clientId": "oesT4Aw5h2aTW6M0gRn0PlpNQ4", "clientSecret": "4OdMIGkaUu-7gIH7jqapOF_Fa4X6Cp7LESA", "attributesRequestMethod": "GET", "issuer": "https://dev-rkamcs4h0sx5no.us.auth0.com", "authorizeUrl": "https://dev-rkamcs4h0sx5no.us.auth0.com/authorize", "tokenUrl": "https://dev-rkamcs4h0sx5no.us.auth0.com/oauth/token", "userInfoUrl": "https://dev-rkamcs4h0sx5no.us.auth0.com/userinfo", "jwksUrl": "https://dev-rkamcs4h0sx5no.us.auth0.com/.well-known/jwks.json", "authorizedScopes": "openid profile email", "attributeMapping": { "name": "name", "given_name": "given_name", "family_name": "family_name", "email": "email", "username": "sub" } }

Checkmark

Task

Details

Provide a JSON file that maps OIDC attributes from your environment to Bunchball.

The file must contain the provider's configuration, including all necessary endpoints, tokens, and other metadata. Show me an example

SAML Checklist

The following are required to use SAML authentication. Bunchball may request additional information as needed. After receiving this information, Bunchball will provide your SAML callback URL and SAML service provider identifier.

	Task	Details
	Ensure your Identity Provider (IdP) supports SAML 2.0.	As a reliable party, Bunchball is dependent on your access to an IdP that supports SAML 2.0.
	Provide a JSON file that maps SAML attributes from your environment to Bunchball.	The file must indicate the SAML schemas that will map to gamification_id and preferred username. Additional mappings might include an email address. Show me an example Copy `{ "preferred_username": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "custom:gamification-id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" }` A list of the common standard SAML identity claims is available at http://www.miicard.com/for/developers/ws-federation/supported-saml-claims
	Provide the descriptive name of your Attribute Statement to Bunchball when using Okta as an IdP.	Although the Okta configuration indicates that the attribute statement is optional, it is required for integration with Bunchball. Configure the SAML Assertion Attribute by selecting the Okta attribute that will be used to map to Nitro gamification IDs (for example, user.email), add a descriptive name (for example, UserEmail), and then provide the descriptive name to Bunchball for configuring the attribute mapping for your SAML SSO flow. Show me this in Okta https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta
	Provide metadata documentation as an XML document or publicly available URL to Bunchball.	If you have a customized logout URL, this should be included in the metadata file. Otherwise, the standard logout URL will be used. The following provides information on retrieving metadata for common identity providers. Microsoft Active Directory Federation Services (AD FS). You can download the SAML metadata document for your AD FS federation server at https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml. Okta. Once you configure your Amazon Cognito User Pool as an application in Okta, you can find the metadata document in the Admin section of the Okta dashboard. Choose the application, select the Sign On section, and look under Settings for SAML. The URL should look like https://<app-domain>.oktapreview.com/app/<application-ID>/sso/saml/metadata. Ping Identity. For PingFederate, you can find instructions for downloading a metadata XML file on their documentation site under "Provide general SAML metadata by file". Auth0. You can get the metadata download document from the Auth0 dashboard. Choose Clients > Settings > Show Advanced Settings, and then look for your SAML metadata URL. It should look like https://<your-domain-prefix>.auth0.com/samlp/metadata/<your-Auth0-client-ID>. Show me an example Copy <EntityDescriptor entityID="urn:bunchball.auth0.com" xmlns="urn:oasis:names:tc:SAML:2.0:metadata"> <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <KeyDescriptor use="signing"> <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"> <X509Data> <X509Certificate>MIIDATCCAemgAwIBAgIJFoNNj+8ecFVdMA0GCSqGSIb3DQeMRwwGgYDVQQDExNidWxctTaxBBizvciphzwriPScIYRm4WX87/vzreF6yQHDbLQYwfLuTW8Vkzs6UXzbs18tj6wdJ4buMKj/bnTRpua6n3obcS1KLwavk5U0X+/Fj914ms83fK1UksllRRjmkKBS+hVy qcg9FsX48KYXCwbE/hURTLtgjDepfiqd92quc0fh+xyeeu3k9DDz3zQsf04mvgEdiaOSUfzE887/jjG+cA+cBX54uuhXNzxzqSBAf8EBTADAQH/MB0GA1UdDgQWBBS4odKFLT0D0Cb6JujJfN1ZELBQADggEBACa1FD3r4n5X6/dxieP2ohXOTyGB7OATJHa0B9v8wUDY9/zGUAzg0Tue9a jQFOuhaYGAAy25K2TCDpSm0kV18RcLij6lm8ETZnDEFPWk573YiQ/8aRtIwL9lQA3fx7UTTqZ2+e7Q+MqE7Kw0gW7citx5wdeN081RWWpUEqOdAzN4IP4l6TVcBHdMrmitDgDUnzCFd5Zel83hRBx5T0ie3HX0s1A/8Hv2c057CWMZJ3iw541RrNpnMARYgAhhaNM5083fOCL3O/bjTwdqO pNpVwJNA=</X509Certificate> </X509Data> </KeyInfo> </KeyDescriptor> <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://bunchball.auth0.com/samlp/Qm289585vElQdprGX7g05uJJ7qDYGlmm/logout"/> <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://bunchball.auth0.com/samlp/Qm289585vElQdprGX7g05uJJ7qDYGlmm/logout"/> <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat> <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat> <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat> <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://bunchball.auth0.com/samlp/Qm289585vElQdprGX7g05uJJ7qDYGlmm"/> <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://bunchball.auth0.com/samlp/Qm289585vElQdprGX7g05uJJ7qDYGlmm"/> <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="E-Mail Address" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/> <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Given Name" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/> <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Name" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/> <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Surname" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/> <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="Name ID" xmlns="urn:oasis:names:tc:SAML:2.0:assertion"/> </IDPSSODescriptor> </EntityDescriptor>