Skip to main content

API Setup to Add BYU User Accounts

Request API access so BYU users can sign in to the application

Overview

This assumes you have the BYU Account module in your project. The BYU Account module is included in the BYU Starter App.

To allow BYU users to sign in to your application with CAS single sign-on you need access to the BYU Persons API (Application Programming Interface). The Account Management page in your application is where you manually add users that you look up from the BYU Identity repository via the Persons API. You can also set up your application to have BYU user accounts automatically added when they sign in the first time (add link). The Account Management page looks like this:

account users administration page image

Setting up and requesting access to the API will take about 30 minutes but it can take a day or more for permission to be granted. Here's how to set up API access to add user accounts.

  1. Create application in BYU API manager
    1. Use API key in your application
  2. Request Service Account linked to API key
  3. Request elevated data access to Persons API for Service Account
  4. Verify that the Persons API works in your application

1. Create Application In Tyk Credentials

The BYU Developer Portal at developer.byu.edu has a wealth of information on BYU APIs and Events. This is a great resource for learning about APIs in general. You can also look up BYU APIs here with links to the Tyk Credentials and BYU InfoHub to create an API Manager application and request data access.

a. Sign in to the Tyk Credentials at https://tcm.byu.edu/index.html and Select your desired Environment (Sandbox or Production)

b. Select Create a New Client (at the top), add your App Name and Generate Secret.

c. You will want to Copy the Client Secret as this is the only time you will be shown the client secret.

You will use the Consumer Key when you request a Service Account. Keep the Consumer Secret private. The Consumer Key and Secret don't change. The Access Token is good for 1 hour. After that a new one can be regenerated from the Key and Secret.

d. You will be automatically assigned to the Person V3 for this to work.

Use API Key In Your Application

*New Mendix Versions (BYU Open Authentication Version 2.0.0+)

We have moved the Client ID, Client Secret, Token URI, Auth URI and Callback URI to constants with the Mendix Modeler. You will find the constants in the BYUOpenAuthentication Module > _USE_ME > Constants. Enter the following:

  • Client ID: (the Consumer Key from the API manager above)
  • Client Secret: (the Consumer Secret from the API manager above)
  • Root URI: https://api.byu.edu
  • Token URI: https://api.byu.edu/token
  • Auth URI: https://api.byu.edu/authorize
  • Callback URI: (usually leave blank)

Most BYU Mendix applications use the OAuth 2.0 Client Credentials grant type to access BYU APIs. If your application uses the Authorization Code grant type—to use the CougarCash API, for example—you will need to enter the Callback URL registered with the application at api.byu.edu in the Callback URI field. See OAuth 2.0 Grant Types to understand the differences.

Click on Save then Get Client Token to validate that the ID and secret work. An Access Token should appear on the right under the Client Token.

The Client Token is good for only an hour. You don't have to keep requesting a new token every hour. If you look at the SUB_Account_Update microflow in the BYUAccount module you see a microflow call to ACT_ClientToken_GetToken just before it makes a REST call to the BYU Persons API. The ACT_ClientToken_GetToken microflow call will automatically request a new token if it expires. If you create a microflow that calls a BYU API, just include the ACT_ClientToken_GetToken before the REST action.

Your API key will only give you self-service access to see your own information and that's it. It won't allow you to search for other BYU people, or even yourself. You need to request elevated access to more data with a Data Sharing Agreement and request a service account that will be linked to your API key. The following steps describe this process.

*Older Module Versions (BYU Open Authentication Version 1.3.1 and older)

In your application, navigate to the BYU API Settings page under the Admin menu. The title on the page says OAuth Configuration. Enter the following:

  • Client ID: (the Consumer Key from the API manager above)
  • Client Secret: (the Consumer Secret from the API manager above)
  • Token URI: https://api.byu.edu/token
  • Auth URI: https://api.byu.edu/authorize
  • Callback URI: (usually leave blank)

Most BYU Mendix applications use the OAuth 2.0 Client Credentials grant type to access BYU APIs. If your application uses the Authorization Code grant type—to use the CougarCash API, for example—you will need to enter the Callback URL registered with the application at api.byu.edu in the Callback URI field. See OAuth 2.0 Grant Types to understand the differences.

BYU API Settings page image

Click on Save then Get Client Token to validate that the ID and secret work. An Access Token should appear on the right under the Client Token.

API Settings menu with access token image

The Client Token is good for only an hour. You don't have to keep requesting a new token every hour. If you look at the SUB_Account_Update microflow in the BYUAccount module you see a microflow call to ACT_ClientToken_GetToken just before it makes a REST call to the BYU Persons API. The ACT_ClientToken_GetToken microflow call will automatically request a new token if it expires. If you create a microflow that calls a BYU API, just include the ACT_ClientToken_GetToken before the REST action.

Your API key will only give you self-service access to see your own information and that's it. It won't allow you to search for other BYU people, or even yourself. You need to request elevated access to more data with a Data Sharing Agreement and request a service account that will be linked to your API key. The following steps describe this process.

2. Request Service Account Linked to API Key

To use a BYU API like Persons (v3) users create an account with the API manager and generate an API key associated with that user account (see Create Application in Tyk Crediential above). This is okay when developing applications but production applications should use an API key associated with a "non-person" account created just for that application, known as a "service account".

The service account is linked to the Consumer Key of your application in the BYU API manager (see below). If you leave, an administrator can link the service account to a different BYU employee. It's best to get a service account before requesting a Data Sharing Agreement so you don't have to request a DSA more than once.

To set up and manage a service account follow these steps: https://developer.byu.edu/data/api-usage/request-a-service-account

3. Request Elevated Data Access to Persons API for Service Account

THIS SECTION HAS BEEN DEPRECATED AND NEEDS TO BE UPDATED WITH THE NEW PROCESS ONCE IT HAS BEEN DEFINED.

To get elevated access to the Persons API or any other BYU API used by Mendix, you request a Data Sharing Agreement. You can do this from infohub.byu.edu. In this example we'll start from developer.byu.edu.

Important: the data sharing request is reviewed by the steward of that data. Data stewards want to make sure the data being accessed is necessary and appropriate for the application or use case. Their primary responsibility is to protect private data and make sure it is not disseminated or used inappropriately or in ways that violate federal privacy laws. Violations can result in severe penalties for BYU. Keep this in mind when you request this data and ask for only the very minimal amount needed for the application. In the instructions below, an explanation for how the data is used will be included so you can decide if you need that data or not for your application.

a. Search for "persons" at developer.byu.edu and select Persons.

Developer website search for persons API image

b. Select the Visit InfoHub button on the lower right.

Developer-visit-infohub.png

c. In InfoHub, there are several fields that could be used in the BYU Account module depending on your needs.

basic

The most basic data needed for every Mendix application to allow users to sign in or be added as users is under the basic category. All Mendix applications need this and the data stewards are usually quick to approve. Expand the > basic field to see the specific fields under it and mark each one listed below with a checkmark.

> basic

  • byu_id
  • name_lnf
  • net_id
  • person_id
  • preferred_first_name
  • preferred_name
  • surname
Info hub basic fields image

employee_summary and student_summary

If you need to differentiate between students, employees, and non-BYU people, you will need three additional fields from the employee_summary and student_summary categories. Even though it's only a few fields, because this requests employee and student data, the data stewards will want to know why you need that data. Expand the > employee_summary and > student_summary fields to see the specific fields under it and mark each one listed below with a checkmark.

> employee_summary

  • employee_classification_code
  • employee_standing_code

> student_summary

  • eligible_to_register
Info hub employee and student fields image

Finish Request For Elevated Access And Submit

d. Press the Add To Request button when you are done then the View Request button.
e. Verify the Requestor and Sponsor Information and fill in the rest of the fields.

  • Development Shop: (locate yours from the list)
  • Application or Project Name: (add a new name if your application or project is not listed)
  • Additional Information Requested: Please also link the service account (123456789 or whatever) to this request.
  • Description of Application or Project: (fill in)
  • Necessity of Data: (use the following or something similar) This Mendix application uses a few fields from the Persons API to retrieve basic information about users when adding their account to the application to grant them access to use it. This is a common function of all BYU applications developed with Mendix.
  • Scope and Control: (use the following or something similar) Only application administrators will be able to see this data. They have signed a non-disclosure agreement indicating that they will not share this private data with others and they have received FERPA training.
Infohub-request-form.png

6. Review the Standard Data Usage Policies and Trusted Partner Security Standards at the bottom and select Submit Request.

You will receive an email with updates about the progress of your request.

4. Verify That The Persons API Works In Your Application

When you have completed the steps above and the Data Sharing Agreement has been approved, you should be able to go into your application and add a user account.

a. Go to Account Management under the Admin menu and select the Add button.

Application account management page image

b. Search for a BYU person by Net ID or name. You should see names appear in the list as you type. If you get an error, check that you have entered the API key and secret correctly and that your data sharing agreement has been approved.

Application account management add user image

c. Select the Add button and you will see the user added to the list of users. You can select Edit to assign security roles to the user to grant access to the application.

Application account management user list image