Domains› Core Concepts› Security› Rock Authentication›

Add an OpenID Client

Let's see how to configure Rock as the authentication server for an outside system. You'll probably want to set up Rock at the same time you're setting up the client system. There's information Rock will need about the client, and the client will need some things from Rock, so it makes sense to have both up at once if you can.

Adding OIDC Clients in Rock

Each external system you're working with will need their own OIDC Client configuration in Rock. In the below example, we'll be setting up Rock to interact with Church Online Platform (ChOP). A little later in the next section we'll show you how things look in ChOP so you can see how everything connects.

To start, navigate to Admin Tools > Settings > OpenID Connect Clients. From here you can view the clients you already have set up or add new ones to the list. In this example we'll be adding a new client for ChOP.

  1. Name - Be sure to provide a descriptive name, so you can easily distinguish between clients.
  2. Client ID - The Client ID is a critical part of what connects Rock and the client. It must be exactly the same for both systems or the process won't work. The Client ID should be created in Rock using the Generate Id button, and then copied from Rock to the client system.
  3. Client Secret - If you think of the Client ID as a username, then the Client Secret would be like a password. Like the Client ID, the Secret must match exactly between both systems and can initially be generated by clicking the Generate Secret button in Rock. You only get one chance to see the Client Secret when you first generate it, so if you lose track of it, you’ll need to generate a new one.
  4. Redirect Uri - After the person has provided their credentials, they will be redirected back to the client via the path indicated here. As you'll see in the next section below, this URI is provided by the client system.
  5. Logout Redirect Uri - When the person logs out of the client system, they can be taken to the URI listed here. In this case, we're using the "Church Online Platform Origin" provided by ChOP, but you can choose a different path. Just keep in mind that the client system chooses whether or not to use this URI. If you log out of the client system and aren't taken to the path provided here don't worry, it just means the client system isn't using it.
  6. Scope Approval Expiration - This is basically the amount of time, in days, that we're allowed to send someone's information. After this time period elapses, permission from the person (scope approval) needs to be obtained again.
  7. Allowed Scopes and Claims - This is where you can choose what information the client system can get from Rock. Keep in mind the client must specifically request this information. For instance, checking the ‘Address’ box doesn’t mean a person’s address will be sent to the client every time they log in. By checking the box, you’re saying that the external system is allowed to have that informationifthey request it.

Tip

Changing Scopes and Claims
If you want to get really advanced, Rock lets you change the list of Scopes and Claims. You can access the OpenID Connect Scopes configuration from the OpenID Connect Clients page at Admin Tools > Settings > OpenID Connect Clients. Just remember that this requires coordination with (and possible changes to) the client system, to support the updates you make.

Example Client System Setup

Each client will be a little different, so it’s challenging to provide specific instructions that apply to any system that’s out there. In this section we’ll use Church Online Platform (ChOP) as an example client, but the same key points will apply to any system that supports OpenID Connect.

First, you’ll need to log in to ChOP. If you don’t have a login, you can create one here. When you’re logged in, you'll need to access the Admin menu. If you're not already there, there's a button near the top-left where you can "Go to Admin". From the Admin menu, click "Integrations" on the left, then select "OpenID Connect” and click the “Set Up” button. You’ll then be brought to the page pictured below.

This page has fields for information you’ll need to get from Rock, and it also provides information you’ll need to add to Rock. As we mentioned earlier, this is why it's a good idea to set up both systems at the same time.

  1. Callback URLIn this example we need to use the Callback URL from ChOP as the Redirect Uri discussed in the prior section. This will always be pointed to the client site.
  2. Church Online Platform OriginThe Platform Origin is sort of like a homepage. In this case, ChOP has provided us with the public URL that Rock Solid Church uses for our online services. This is a logical place to bring people when they log out of ChOP, so we've used this as our Logout Redirect Uri in Rock as shown in the prior section above.
  3. Issuer URIThis will be your organization's website. Specifically, this needs to be the Public Application Root in Rock's Global Attributes. If you're having trouble connecting with a client, try using https instead of http for your Public Application Root and make sure it exactly matches what's in the client system, including the /at the end.
  4. Client IDYou'll populate this with the Client Id that was generated from Rock, as described in the prior section above. It is critical to the process that the Client ID is exactly the same between both systems, so this is one of the first things you should check if things aren't working.
  5. Client SecretJust like the Client ID, this will be generated in Rock and then copied over to the client system. Also like the Client ID, the Client Secret needs to be exactly the same between both systems. Remember, Rock won't show you the Client Secret after it's been saved, so if you need it and can't access it, you'll have to generate a new one and copy it over to the client.
  6. Test ConfigurationChurch Online Platform gives you a handyTest Configurationbutton to make sure both systems can communicate with each other. If something's wrong, ChOP will let you know what it is. If the test is successful, all you'll need to do is confirm your email address to finish the setup.

With the above setup in place, your staff and guests can immediately start using their Rock credentials to log in to Church Online Platform. Again, we've been using ChOP in this example, but you'll find any system that supports OIDC uses similar (if not identical) terminology and configuration.

Warning

Unique Email Addresses
Be aware that ChOP has a 'unique email' policy so only one person can have any particular email address. If people have shared email addresses in Rock, they will receive an error message when the second person attempts to log in using OpenID Connect with ChOP.



Intro to OpenId Connect Advanced