Single Sign On allows you to implement your Rock login in Subsplash app and web tools, this means users only have to remember one set of credentials for all of your tools but also gives you full control over the login experience for your users on the Subsplash platform whether it be in the app, giving, messaging, etc.
SSO is not required to use the plugin, but we do need the OIDC credentials from you to configure the plugin. SSO can be enabled right away or at a later date/time after the initial setup of the plugin.
Out of the box, Subsplash offers Email (Subsplash account), Google, and Apple as login methods to create a Profile. Enabling SSO will disable those to force your Rock login.
Setup and Configuration
These will be the initial steps to get SSO prepared for Subsplash mobile and web apps.
OIDC credentials
OIDC is the foundation to a single sign on experience between Rock and Subsplash. We will use these credentials to establish your login that can be used in Subsplash app and web tools.
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”
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 the secure doc.
For Client Secret, click Generate Secret and copy that secret into a safe place to give to Subsplash as well via the secure doc. 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 that is completed, paste your Id and Secret in to the secured doc shared by Subsplash for setup.
Custom Profile Pages
When you opt for SSO, a custom profile page is required to ensure users can update their information in Rock. This is a web page you build in Rock, usually dedicated to the mobile app and not used on your external site, but give to us to replace the default profile page coming from Subsplash. This lets your users see their profile/account directly in Rock and change information that otherwise wouldn't be connected to Subsplash.
There are some requirements for this page to comply to app store polices. We highly recommend creating a new site for these dedicated app pages that way you have better control between the pages on your website and in the app.
Navigation
This should be a very simple page with no header/footer that allows navigation to other pages on your site, except for ones directly related to the profile and in the contents of the page.
Logout
Users will need to be able to log out from their account. The app needs a native command to do so and can be dispatched from a deep link. Add a button to your site with the following URL to add your log out functionality:
subsplash://sap/eyJoYW5kbGVyIjogImFwcFVzZXIiLCAiY29tbWFuZCI6ICJsb2dPdXQifQ==
Account Deletion
App stores require the ability for a user to initiate account deletion if they are logged in. Without this ability the app is at risk for removal from the store and will not be allowed any updates.
There are several paths do doing this, we recommend following Apples policy guidelines.
Once this page is complete please provide the URL to us in the secure doc to set live.
Custom Profile Header
A profile header is whats displayed at the top of Subsplash apps where you see initials or a profile picture while logged in. Out of the box this is supplied by the Subsplash Profile but similar to a custom profile, you will supply us an endpoint for a custom profile header.
This will need to be an endpoint that returns a JSON object rather than a web view. And can be configured in the plugin > Custom Web Services > Create a new webhook:
{
{% if CurrentPerson %}"title": "{{ CurrentPerson.FullName }}",{% endif %}
"subtitle": "{% if CurrentPerson %}{{ CurrentPerson.NickName | Slice:0,1 }}{{ CurrentPerson.LastName | Slice:0,1 }}{% endif %}",
{% if CurrentPerson %}"image":"{{ 'global' | Attribute:'PublicApplicationRoot' | ReplaceLast:'/','' }}{{ CurrentPerson.PhotoUrl }}",{% endif %}
"actions": [
{
"handler": "browser",
"style": "internal",
"contentUrl": "{{ 'Global' | Attribute:'PublicApplicationRoot' }}myaccount",
"authProviderId": "{{authProviderId}}"
}
]
}
Once this is done, include this URL in your secure doc so we can set this endpoint as the custom profile header.
Advanced Configuration Options
Bypass the permissions page
Rock’s default OIDC integration has a requirement to review and manually click "Yes" on the "Give Permission" page during the authentication process.
Sometimes Subsplash clients wish to bypass this in Rock which can be done by adding an HTML Content block to the /Auth/Authorize page. The easiest way to do this (since loading the page requires specific parameters) is to just pull it up in the Toolbox -> CMS Configuration -> Pages menu. The Give Permission page can be found under Internal Homepage -> Admin Tools -> Security -> Give Permission hierarchy in the pages menu:
In the Blocks From Page section for the Main Zone a new HTML Content block can be added with the following HTML:
<style>
div.authorize {
display:none;
}
</style>
<script type="text/javascript">
$(document).ready(function() {
window.location.href = $('div.authorize').find('div.actions>a.btn-primary').attr('href');
});
</script>
Redirecting . . .
The Redirecting . . . text content can be customized to match your organization's branding and design.
Rock site theme 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.
Personalized App Content
A major benefit of integrating your Rock login is the ability to personalize content to users who are logged in or not.
Once a user logs into the app, that authorization gets passed everywhere they go, and even if the user is taken from the app out to the mobile browser.
Push Notifications
Now that you know someone is logged in, send them or a group a personalized push notification.
Groups & Messaging
If using Subsplash Groups & Messaging you can sync Groups and group membership of People between Rock and Subsplash. This allows you to take advantage of Messaging in your Subsplash app and web.
Rock Web Pages
The simplest approach to do this is by using Rock web pages in your app. Once logged in the user could open a connect card in Rock and have the form auto-filled with their details automatically, a profile page could be displayed in the app that allows them to edit their household and personal information, plus more.
Custom App Feeds
A more advanced approach to personalized content is with custom feeds. In the plugin > Content and/or Custom Web Services you can set up feeds to plugin into your app that come from Rock, allowing you to use your choice of lava or security roles to show/hide items to certain users and segments.
Frequently Asked Questions
Why am I seeing "Object moved to here” message when you try to login?
Rock 17.1 introduced some changes related to OIDC, which is what we use for SSO. You need to make sure a Login page is set for your External Site handling the OIDC routes like /Auth/Authorize.
How long does a user stay logged into the mobile app from Rock?
The short answer is two weeks if the app has not been used within that timeframe.By default, Rock has three different OIDC tokens used in the lifetime of a user’s login. For developer’s reference, this is Rock Core, so it is not configurable.
The first is the Identity Token, which is used during the authentication handshake. Once the user clicks that they want to log in and enters their credentials, that user must finish the entire login process within 20 minutes.
The second is the Access Token. When the access token expires, the application can use the refresh token to obtain a new access token. It can do this behind the scenes, and without the user’s involvement so that it is a seamless process for the user. This token is good for 1 hour.
Lastly, the Refresh Token. This is used to re-authenticate a session to get a new Access token. By default, this token is good for 2 weeks.
I can get to the login screen on the mobile app, but once clicked to login - then it fails.
In Rock, make sure your “Public Application Root - Global Attribute” is correct, and that it starts with “https”.You can find this Global Attribute if you go to Admin Tools > General Settings > Global Attributes > Public Application Root.
Make sure the Public Application Root value starts with “https://”, and that https is enabled. If you just made this change, make sure to restart Rock before trying again.
What if my users were previously logged in with Apple, Google, etc?
Great question, when we removed one of these login options the app will force logout the user the next time they open the app so you will not have to communicate any steps to your users that involve logging out before continuing with your Rock login.