Setup - Subscribe to the API & Generate Keys
To generate the token one must first subscribe, subsequently you can just "regenerate" the token.
- Access the API store via https://api.ucsd.edu/store (for now you have to make a hosts file change to skip the LB and you have to use port 9443 for this to work.)
- Create and Application (or use your "default application".
- Select the WebReg API and subscribe your application.
- View your subscriptions and Generate a production key (I'm not sure if sandbox will work).
- The token that is generated should be used by your code to access the API. (This token is good for an hour, you can regenerate the token when you need or we can change the duration in the DB if necessary)
Test the API with Bearer
Test that the token works and everything is wired up right by using curl.
curl -H "Authorization :Bearer 441aae1cb1ad1584cec2334d61eb25b5" https://api-dev.ucsd.edu:8243/webreg/2.1.0/schedule/editEnroll
Replace the token with the bearer token you just (re)generated. You should get a response from the WebReg api indicating "Insufficient Parameters" or something similar.
Note: if you are skipping the Load Balancer and accessing the gateway directly, curl will complain about the certificate it is using. Add the -k option to prevent SSL certificate verification..
Request a Client Credentials token via API
You can generate a token directly without using the web UI by using curl. On the My Subscriptions page https://api-dev.ucsd.edu/store/site/pages/subscriptions.jag click the "CURL" button then select Client Credentials. You should get a command like:
curl -d "grant_type=client_credentials" -H "Authorization: Basic VDdnbXRrVWdFaGlWRHo1djJlNTNKeEpSSnQ4YTpEVUpVN0dwNFNHOHhJa0ZHRF8zUzk4UUVDYmth, Content-Type: application/x-www-form-urlencoded" https://api-dev.ucsd.edu:8243/token
The element after Authorization: Basic is the Consumer Key and Consumer Secret separated by a :, base64 and url encoded. Invoking this command should get a new bearer token:
{"token_type":"Bearer","expires_in":2916,"access_token":"4130324514115d1a533baa4c1696283"}
Implicit Authentication to get Token
Another method for getting a token is to redirect the user to the Key Manager to authenticate with it. The user will then be redirected back to your app with the token on the URL. The use case here is that a user hits your application, when a token is needed the user is sent to authorize. When your page is reloaded JavaScript can be used to retrieve the code from the URL and invoke the APIs via AJAX.
- Register your applications Callback URL (https://api.ucsd.edu:9443/store/site/pages/applications.jag scroll to bottom, click edit on your application). This is where the browser will be sent once the token is retrieved. For testing it doesn't need to actually work, we can check the browsers info to verify the token is generated.
- Open a browser to http://api.ucsd.edu:8280/authorize?
response_type=code&client_id=T7gmtkUgEhiVDz5v2e53JxJRJt8a&scope=TEST&redirect_uri=http://localhost/myApp after replacing the ConsumerKey and the RedirectURI (with your callback url, they must match). - Check the location that your browser was sent to, it should be something like: http://localhost/myApp?code=bd77892b4953c49376cbc31ed7d9c55
SAML2 Bearer Auth
Another way to request a token is to get the SAML Assertion that's sent from the SSO Server and pass it to the Key Manager. The Key Manager is configured to trust the SSO Server so it will issue a Client Authentication token for the user mentioned in the SAML Assertion.
curl -X POST -k -u "4ppy0unf2TGPUyAbHgwBgM2Enfoa:nLmLl06rRHEgX0C9yxxD1rxyEUQa"
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
-d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion={Base64 URL encoded Assertion}" https://localhost:9443/oauth2/token
For more information, refer to blog at http://soasecurity.org/2014/10/31/saml2-bearer-assertion-profile-for-oauth-2-0/