This page has moved. You will be redirected in 5 seconds. Please bookmark the new page.

SSO Tutorial with ON API

  • Introduction

    Follow these steps if you have custom apps or 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. If the end-user is already logged into an ON session, the redirect to the TPA will happen seamlessly, without the need to login a second time.

    Questions about implementing this SSO? Ask your questions here.

  • Step 1 – Initial Setup

    1. As a Platform Manager, navigate to Core > Security > Authentication 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",
       "post_url": "https://SCHOOLNAME.myschoolapp.com/api/sso/auth/test-sso"
       "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. Modify the file extension of .env.example by removing .example.

    6. Fill in the placeholders labeled in the .env file with data from the corresponding locations; you should now be able to validate the token.

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

    7. To get additional information about the user, such as First/Last/email/username, perform a POST to the post_url variable obtained in the JWT (Step 2.3).

    The body of the POST should contain a key, which is a SHA512 hash of the Secret Key and the received JWT token, and the JWT token you received during the SSO process.

    See the code in index.php on GitHub for an example.

    {
          "email": "ian.smith@gmail.com",
          "user_name": "iansmith",
          "user_id": 2844867,
          "firstname": "Ian",
          "lastname": "Smith",
          "host_id": "faculty_iansmith",
          "key": "9BDD254156D1BD6DDF1C3BEEAA3C76EB5CB19C4677940B3BC535CB8D97C8BE5976DAEF440F902D9E772070EE18B3EBE0E0D007412B2166A0FAC3B97E90CC47DF",
          "JWT": "eyJ0eXAiOiJQQ1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MjMzNjcwODcuNDM3NjY5NSwianRpIjoiZTYxYjY2YTgtNTIyNy00NTQzLWI0NjgtNTc4MWUwODkyYzdlIiwidWlkIjoyNzE2ODQzLCJleHAiOjE1MjMzNjc0NTcuNDM3NjY5NSwibmJmIjoxNTIzMzY3MDg3LjQzNzY2OTUsImlzcyI6Imh0dHBzOi8vMjMwMTUubXlzY2hvb2xkZW1vLmNvbSIsImhpZCI6IiIsIm9uYXBpIjoiaHR0cHM6Ly8yMzAxNS5teXNjaG9vbGRlbW8uY29tL2FwaS91c2VyLzI3MTY4NDMiLCJwb3N0X3VybCI6Imh0dHBzOi8vMjMwMTUubXlzY2hvb2xkZW1vLmNvbS9hcGkvc3NvL2F1dGgvc3AifQ.Y0rNdweccIsJB0qrahD2yT0gmKl1VK6kKKSQCjXvutI"
      }
      

    Note: An API account is not required to make this POST call.

    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 > Additional content types > Links (This can also be reached via onMessage > Content > Additional content types > 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 > Content > 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 > Security > Authentication 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

Comments

Have a question? See a problem with our docs? Want to engage with the ON API team? Please visit us on the ON API Community!