Getting Started
In setting up OpenID Connect (OIDC) you will generate some data to send to Subsplash. Subsplash will set up part of the authentication and then send data back to you to complete the setup of your API client.
Prerequisites:
Rock RMS Version 14.4 or higher
This version is necessary for the addition of OpenID Connect (OIDC).
Contact Subsplash
Please contact your Customer Success Manager (CSM) or Account Manager (AM) if you have not been talking with them. If you are not currently a Subsplash client, please connect with us.
If you have any trouble setting up this plugin beyond the scope of this documentation, please contact your Customer Success Manager (CSM) or Account Manager (AM) and we will work through it with you.
Key Terms
Subsplash App Key
This is available in your Subsplash Dashboard displayed near the bottom of the home page.
Rock OIDC Credentials
You will generate a Client Id and a Client Secret in Rock to send to Subsplash.
Base URL
Your Rock login page, either default or custom - “my.domain.com”
Subsplash Auth Info
Shared via a secure document during the setup process.
This Client Id and Client Secret are different from the ones you generate in Rock.
Push Notification Endpoint
Token Endpoint
App Key (should match the one you sent)
Client Id
Client Secret
Auth Provider ID
Public Payment Key
Setting up OpenID Connect (OIDC)
To start, navigate to Admin Tools > Security > OpenID Connect Clients. Your page should look like the following screenshot:
Click on the + button on the bottom right corner to add a new OpenID Connect Client, and follow the steps below to create a new OIDC client:
Fill out the name as “Subsplash App Platform”
Make sure the Active checkbox is checked.
For Client ID, click Generate Id, and then copy that Id into a safe place. You will be providing this Id to Subsplash in a later step.
For Client Secret, click Generate Secret and copy that secret into a safe place to give to Subsplash as well. Note: this is the only time you will see the client secret, so make sure you make note of it; otherwise, you will have to re-generate it.
For Redirect Uri, you can type or copy & paste the following URL: https://core.subsplash.com/end-user-auth/v1/authproviders/result
Set the Logout Uri to a page of your preference. Usually, this is pointed back to the home page of your church’s website, but this is your choice.
Lastly, make sure all options under the Allowed scopes and Claims are checked.
You can use the following screenshot as a reference to make sure you have everything, and when ready click Save:
Once completed, send the Subsplash App Key, Rock Client Id, and Client Secret via the secured document created by Subsplash. If you have not received this document, please contact your CSM. After you share that data, Subsplash will complete the setup on our side and share the remaining information needed via the secured document to complete Setting up your Subsplash API Client.
Preparing Rock for Subsplash
Rock, by default, has login screens set to the Stark theme under “External Website”. If you were to leave this setting where it is, then your mobile sign-in pages would look like the following screenshots.
Default theme
Default theme
If you like the look of these screens and would like to keep them as is, you can skip this part and set up your communication transport. If you would like to configure the login user experience that the user will see when authenticating with the Subsplash app, there are 2 different options:
If you already use Rock for your public website and your Subsplash app is themed similarly, it is likely you can simply reuse your existing login/registration pages with minimal changes.
You can use the default Rock Stark theme as it is configured out of the box with very minimal configuration changes. This could be as simple as setting up a DNS subdomain such as https://www.rocksolidchurchdemo.com/ and making sure this domain is configured for the external website site within Rock. When the user authenticates within the Subsplash app, they will simply be taken to the external website’s login page (https://www.rocksolidchurchdemo.com/login). By default, this page is preconfigured within Rock with all the registration, forgot account, and other pages. You may, however, want to disable some of the external pages that are not applicable for your organization.
Configure your API Client
At this point, you should have the following from us provided in your secured document:
Push Notification Endpoint
Token Endpoint
Subsplash App Key
Subsplash Client Id
Subsplash Client Secret
Auth Provider Id
Public Payment Key
If anything is missing, please reach out to us again.
Go to Admin Tools > Installed Plugins > Subsplash > Settings and add a new API client with the + button.
Once you have completed all settings, click Save.
At this point, you have completed the minimum requirements to use the plugin for Single Sign On in Subsplash. The rest of this article will go into setup for specific parts of the plugin to take advantage of the full feature set like Push Notifications, Donation Sync, etc. What you set up is up to you and what you want to use.
Create REST Key
The REST key will be used in Push Notifications and your Communication Transport to send notifications from the Subsplash platform.
If you are a Subsplash Giving user and use the legacy Rock RMS Integration you may recall setting up a REST key in doing so, please note that the same REST key should not be used for the notification feature.
In your Rock Dashboard, navigate to Admin Tools > Security:
Click on REST Keys:
Add a REST Key by clicking on the + sign on the right:
Create a new REST Key with the Name "Subsplash Plugin", click Generate Key to set the key, then click Save:
Navigate back to Admin Tools > Security and click on REST Controllers:
Find the Subsplash Controller (Controller Type: com.subsplash.Rest.Controllers.SubsplashController) and click on the Security lock icon on the right end of the row and you will see a modal popup:
Clicking on the name or type will take you to a different screen
Add View and Edit permissions. With View selected, click Add User and find the Subsplash Plugin user created above:
With Edit selected, click Add User and find the Subsplash Plugin user. Check that they have Allow selected. Click Done to close the modal:
Setting up your Communication Transport
To set up your communication transport, navigate to Admin Tools > Communication > Communication Transports
Click on the “Subsplash” communication transport, and a panel should pop up. Select your Subsplash API client from the dropdown, and make sure the Active dropdown is set to Yes. If you do not see your client please double-check the steps above to make sure its been configured.
Next, you need to activate push notifications. To do this, navigate to “Communication Mediums”. You can find the Communication Mediums page in Admin Tools > Communication > Communication Mediums
On the communication mediums page, click on Push Notifications. Then make sure Active is set to Yes, and select Subsplash as your Transport Container. The following screenshot shows what that looks like:
Financial Gateway
If using the Giving or Event Registration portions of the plugin you will need to set up your financial gateway in Rock. This starts by adding your Public Payment Key that is provided by Subsplash in your secured credential document.
Click into your Installed Plugins > Subsplash > Settings then select your API Client and paste in your Public Payment Key along with the rest of the details from the steps above:
Head to System Settings > Financial Gateways and add a new Gateway. Select Subsplash Gateway and your Subsplash API client:
Activate the Gateway and click Save.