Implementation of OneRoster API Security

Dereck @ ims responded via email, so I am adding that here in case anyone else would find it helpful.

--------------------------------------

Hi Brandon,
So, there are several questions here. I'll answer them in somewhat random order compared to your email. But in general, you can use support.imsglobal.org to ask any future questions. If I don't pick it up, someone else here at IMS Global will do so.

Firstly, yes, you can use your local machine for development. Since the SSL is at the TLS level, there should be no issue with your using the node.js equivalent of CURL in PHP to make the calls to the OAuth2 server to get the bearer tokens needed. I don't think you will need to install any certificates on your side to do testing. However, if you indeed do have problems here, you (of course) can follow-up later so that we can troubleshoot the issue in a different support case.
​
In your question you do not specify if you are using node to create a consumer or a producer app for One Roster. I'll assume that you are working as a data consumer, because that it is the side that will deal with the OAuth2 token generation before hitting the producer's endpoint. If you are the data provider for One Roster, the situation would be reverse - in effect you will be providing an OAuth2 token generator for your consumers. I _think_, though, that you are asking your questions as a consumer.
​
For One Roster we don't use the JWT version of the Client Credentials grant. The appropriate section is 4.1 (not 4.1.1). So it isn't necessary to use the JWT path to ask for a bearer token. [In LTI 1.3 they _do_ use the JWT path, but not here.] In effect, then, your application must only do the following algorithm in node.js to create the BASE AUTH string needed to get the token - Base64(client_id + ":" + client_secret). To call the OAuth2 server you must have the Authorization header set to "Basic BASIC_AUTH " where BASIC_AUTH is the value that you create with that algorithm. There are other required values, including one other Header (the Content-Type) and two POST form fields (the scope and the grant_type). But in general the Security Specification follows the standard OAuth2 workflow for Client Credentials grant. The endpoint for the Consumer testing to get that token will be https://oauth2server.imsglobal.org/oauth2server/clienttoken (as documented on the CTS instructions page). Once you have the bearer token, then all tests are sent from your app to the One Roster endpoints for /users/, or /orgs/, or as needed with that scoped bearer token in the Authorization header (as "Bearer TOKEN" in this case). The scoped token retrieved from the OAuth2 server will give access to those endpoints, and the endpoints during testing are _only_ secured in the manner that token is valid and the scopes are valid for the calls made.
​
Once all of the calls are made to the CTS suite with the OAuth2 bearer token, you should submit for certification for One Roster Consumer REST with OAuth2. You should never mix the older OAuth1.0a calls with the OAuth2 calls - this will always create a FAIL in one or more tests. However, as you note, both the older OAuth1.0a and the newer OAuth2 workflows work in the CTS suite. The signing is "required" if you are working with the older (still supported) workflow. If your partners aren't using it, though, it wouldn't be needed.
​
_If_ you still need the OAuth1.0a version (with internal signing), you'll need to restart testing and not input the OAuth2 user into the client_id. Clear the cookies in your browser, and restart testing. When you don't input a client_id (the OAuth2 signal), the suite will provide to you a OAuth1 client_id and client_secret for you to use for signing the OR requests. Again, this may or may not be necessary. OAuth1.0a is on a deprecation schedule and at the end of the next 1.5 years we will stop certifying products that use that workflow. At that point all testing for OR 1.1 and OR 1.2 will strictly work with OAuth2 bearer tokens for certification. [The future OR 1.2 cert suite will only use OAUth2 bearer tokens.] It is possible, however, that not all of your partners have yet adopted the OAuth2 workflow for One Roster 1.1. If not, then you will indeed need to redo the certification a second time using the signed requests. Again be sure to do that from the top (so to speak) after submitting for certification for OAuth2.
​
Finally I'll briefly answer your question about the appropriateness of the OAuth2 workflow. In the older OAuth1.0a workflow there is an internal digest by checksum created by the signature. In times past, before ubiquitous SSL, this was appropriate for HTTP only endpoints. You could effectively send information "in the clear", since in theory the signature was done with a one-time-only shared key between parties. If didn't matter that the data was in the clear for most applications, and the receiver couldn't be spoofed into accepting a forged message (since signature collisions were highly unlikely). With the passage of time HTTPS has become (literally) everywhere. OAuth2 takes advantage of this fact in that endpoints can now be protected by this SSL tunneling in every direction. Nothing is ever sent in the clear, so there is no danger in interception of the message. But it is still necessary to protect the endpoints, so this is done with the Authorization header. While OAuth1.0a served well, the truth is that the creation of the signature (especially from scratch) is very, very hard and is error prone during development. All that is now gone. For better or worse everyone moved to the OAuth2 paradigms, and IMS-based workflows are now completely leaving the older OAuth1.0a behind permanently.
​
I hope this helps. Don't hesitate to follow-up if you need more information.
best,
Dereck
IMS Global