JSON Web Token SSO Tutorial with ON API

  • Introduction

    Follow these steps if you have third-party applications (TPA) that would like to use Blackbaud ON Products as the identity and login provider. When an end-user attempts to use the TPA site, they are automatically redirected to the ON Products login screen. After logging in, the user is automatically redirected back to the TPA site. This is done in a secure manner so that we don't expose the username or password.

  • Step 1 – Initial Setup

    1. As a Platform Manager, navigate to Core > Settings > SSO Settings

      Add New

    2. Click Add New

    3. Enter a Name for your new SSO. When you save, the Slug will be generated based on the name you enter.

    4. Enter your RedirectUrl, which is the external URL where the user will be sent with a token from a valid session from the ON products. Be sure to include the {token} placeholder (include the curly braces) in a query parameter in your URL. Settings Modal

    5. Optional: If you want to allow Platform Managers to be able to impersonate a user and SSO into your third party app, make sure that box is checked. We recommend leaving it unchecked if you don't want Platform Managers to be able to impersonate a user and SSO into a third-party app as that person.

    6. Save your settings

    7. Click the Edit button next to the item you just created.

    8. Copy your Secret Key and paste it into a safe place for a future step.

      Your Secret Key is longer than the field, so be sure to select the entire key. Tip: triple-click in the text field to select the whole string.

      Secret Key

  • Step 2 – Your First SSO Test

    1. On the SSO Settings screen, notice the URL next to the item you just created.

      URL

    2. While logged in, point your browser to https://SCHOOLNAME.myschoolapp.com/api/sso/auth/test-sso.

      Notice api instead of app and where test-sso is the Slug of the SSO item.

    3. If everything is working you should see something similar to this:

      {
       "iat": 1502200957.022433,
       "jti": "ecb1ad9d-6418-4f73-a773-2507f59563ac",
       "uid": 2844867,
       "exp": 1502204257.022433,
       "nbf": 1502200957.022433,
       "iss": "https://SCHOOLNAME.myschoolapp.com",
       "hid": "0982-TT-000098755",
       "onapi": "https://SCHOOLNAME.myschoolapp.com/api/user/2844867",
       "aud": "https://thirdpartyappdomain.com",
       "Debug-Status": "Redirect user to sso url",
       "Debug-Token": "eyJ01XAiOxJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDIyMDA2NTcuMDIyNDMzLCJqdGkiOiJlY2IxYWQ4ZC02NDE4LTRmNzMtYTc3My0yNTA3ZjU5NTYzYWMiLCJ1aWQiOjI4NDQ4NjcsImV4cCI6MTUwMjIwNDI1Ny4wMjI0MzMsIm5iZiI6MTUwMjIwMDY1Ny4wMjI0MzMsImlzcyI6Imh0dHBzOi8vc2lzYWNhZGVteS5teXNjaG9vbGFwcC5jb20uc2YuYmJrMTIuY29tIiwiaGlkIjoiMDk4Mi1UVC0wMDAwOTg3NTUiLCJvbmFwaSI6Imh0dHBzOi8vc2lzYWNhZGVteS5teXNjaG9vbGFwcC5jb20uc2YuYmJrMTIuY29tL2FwaS91c2VyLzI4NDQ4NjcifQ.TY6LlUiFgtbA6AneTL2SxBcRaLrMCkU7YgDWwoSIXXc",
       "Debug-Url": "https://www.thirdpartyappdomain.com/path?sso_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDIyMDA2NTcuMDIyNDMzLCJqdGkiOiJlY2IxYWQ4ZC02NDE4LTRmNzMtYTc3My0yNTA3ZjU5NTYzYWMiLCJ1aWQiOjI4NDQ4NjcsImV4cCI6MTUwMjIwNDI1Ny4wMjI0MzMsIm5iZiI6MTUwMjIwMDY1Ny4wMjI0MzMsImlzcyI6Imh0dHBzOi8vc2lzYWNhZGVteS5teXNjaG9vbGFwcC5jb20uc2YuYmJrMTIuY29tIiwiaGlkIjoiMDk4Mi1UVC0wMDAwOTg3NTUiLCJvbmFwaSI6Imh0dHBzOi8vc2lzYWNhZGVteS5teXNjaG9vbGFwcC5jb20uc2YuYmJrMTIuY29tL2FwaS91c2VyLzI4NDQ4NjcifQ.TY6LlUiFgtbA6AneTL2SxBcRaLrMCkU7YgDWwoSIXXc"
      }
      

  • Step 3 – Setting Up Your Third-Party App

    1. Visit jwt.io

    2. Find a Library for the language of your choice. In this example, we'll use a PHP libary by Luís Cobucci.

    3. With PHP, you can use Composer to do this install. After installing Composer, using a command line tool, navigate to the directory you're working in and run: composer require lcobucci/jwt

    4. You can use the following code sample to help you get started:

      View on GitHub

    5. Once you fill in the placeholders, you should now be able to validate the token and grab the UserId of the logged-in user.

      $data->setIssuer('https://SCHOOLNAME.myschoolapp.com'); // School's app domain
      $data->setAudience('https://thirdpartyappdomain.com'); // Third-party app domain
      $secretkey = 'insert_SecretKey_from_sso_settings';
      

      Reminder: Instructions to get your Secret Key are in Step 1 of this tutorial.

    1. On the SSO Settings screen, copy the URL next to the SSO item you created. You'll need this in an upcoming step.

      URL

    2. As a Platform Manager or Content Editor, go to Core > Communication > Content > Links (This can also be reached via onMessage > Content > Links, depending on your role and what products are owned.)

    3. Click Add New Category

    4. Name your category

    5. Click Save & Add Link

    6. Fill out the Title

    7. In the URL field, combine your school's app URL (i.e. https://SCHOOLNAME.myschoolapp.com) with the URL segment from the first step, (i.e. /app/sso/auth/test-sso) replacing the last part, which is the slug. https://SCHOOLNAME.myschoolapp.com/app/sso/auth/SLUG URL

    8. Save

    9. As a Platform Manager, go to Core > Communication > Resource Boards

    10. Next to View Boards, choose the appropriate role, for example, Parent

    11. Click Add Post

    12. Fill out Title, Description, and add a Cover Photo

    13. Under Post Cover Goes to, choose Direct Link

    14. Click Select Category and find the category you made in the previous steps

    15. Click Select Link and choose your SSO link

    16. Save

  • Step 5 – Testing SSO

    1. To begin, login as a Platform Manager.

    2. Then, navigate to Core > Settings > SSO Settings.

    3. Identify the SSO you wish to test, and select Edit within the corresponding row.

    4. Within the Add SSO Settings window, select the checkbox beside Allow Impersonate.

    5. Note: Once you are finished with testing and implementation, it is recommended to uncheck Allow Impersonate. This security precaution is dependent on whether or not the school wants to allow Platform Managers to impersonate a user and SSO into the connected app via their personal profile.

      To learn more about impersonation, click here.

    6. To test your SSO, impersonate either a parent, student, or teacher within the test environment. Use the persona menu to switch between instanced, role-specific areas of the "ON" products.

    URL