CampusNexus Web APIs with OAuth 2.0 Client Credentials

CampusNexus Student has started supporting OAuth 2.0 based authorization with recent 18.2 release. This change will provide ability of calling OData endpoints and other services of CampusNexus Web via passing in a JWT (JSON Web Token) based authorization token. This blog will go over few ways of getting authorization token from Staff STS 2.0 and then subsequently using it to call OData API of CampusNexus Web.

OAuth 2.0 is one of the industry standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

Application Identity with OAuth 2.0 Client Credentials

The flow demonstrated in this documented is Application Identity with OAuth 2.0 Client Credentials Grant. In this flow the token is provided to an application as oppose to end user and API request is made as an application. Following steps and diagram describes the flow:

  1. First, the server application needs to authenticate with Staff STS as itself, without any human interaction such as an interactive sign-on dialog. It makes a request to Staff STS’s token endpoint, providing the credential and Application ID.
  2. Staff STS authenticates the application and returns a JWT access token that is used to call the web API.
  3. Over HTTPS, the web application uses the returned JWT access token to add the JWT string with a Bearer designation in the Authorization header of the request to the web API. The web API then validates the JWT token, and if validation is successful, returns the desired resource.

JWT – JSON Web Tokens are an open standard method for representing claims securely between two parties. You can read more about what it contains and even decode your own JWT based token here: https://jwt.io.

Setup for Campus Nexus Web and Staff STS

To get Client Credential Flow working in CampusNexus there are some setup steps required. These steps will securely enable OAuth 2.0 for your application.

  1. Open your Staff STS server and navigate to StaffSTS\IdentityServer\Config\Clients
  2. Add a new file with personalized name and secret for your application. Following is sample of what you would put in this new file

  1. Open Web.config of StaffSTS and add or edit following AppSetting
    • Key=WsFedIssuerUri, Value=[StaffSTS base URL]/identity
  2. Open Web.config of Campus Nexus Web and modify following 3 appSettings
    • Key=AuthenticationProvider:WsFedIssuerName, Value=[StaffSTS base URL]/identity
    • Key=AuthenticationProvider:ApiClientId, Value=ClientId from step#3
    • Key=AuthenticationProvider:ApiClientSecret, Value=ClientSecret from step#3

Once above setup is done you are ready to consume Campus Nexus WebAPIs using OAuth 2.0. Following are couple of samples.

MVC .Net Application to Web API

This code sample shows how to use OAuth 2.0 from Staff STS to build web applications that call web APIs that are secured by Staff STS. The source code for this sample is available in GitHub under this link: https://github.com/ShahTushar/Cmc (Nexus.Api.OAuth.Sample.sln)

  1. Staff STS 2.0 is built on Identity Server 3.0, so we will use helper library available from same developer for token retrieval. You can install Identity Model for you application via NuGet.

Note: It’s important to note that IdentiyModel is not a required component to complete this flow. A simple HttpClient can also do the job of IdentityModel.

  1. You will have to update Web.config with information about your application. Following 3 appSettings entries should be updated with personalized content.
    1. IdentityProviderTokenEndpointUri
    2. ClientName
    3. ClientSecret
  2. Once basic setup is done, all you need is following code to retrieve access token

  1. Once you have access token you can use it for any API calls to CampusNexus Web. Here is an example on how you will setup the access token on outgoing call. SetBearerToken is extension method provided by IdentiyModel.

Postman to Web API

The token retrieval and usage can happen in any framework. To demonstrate the simplicity and options, here is how you can use a tool called Postman to retrieve token and call CampusNexus Web APIs. Postman is a Google Chrome app for interacting with HTTP APIs. It presents you with a friendly GUI for constructing requests and reading responses. You can get Postman for Windows/MacOs/Linux from https://www.getpostman.com/. We will configure Postman to retrieve OAuth 2.0 token from Identity Server and then use it with CampusNexus Web API call.

Here is how you can use Postman to test API calls

  1. Start by Importing “CampusNexus Identity Server.postman_collection.json” file provided as attachment here.
  2. Double click on AddressType with OAuth 2.0 in the Collection tab
  3. Configure base address of CampusNexus Web correctly in URL tab
  4. Under Authorization tab, select OAuth 2.0 as Type and click on Get New Access Token

  1. Configure Get New Access Token screen. Sample is shown below
    1. Setup correct base URLs for Auth URL and Access Token URL
    2. Configure ClientID and Client Secret to match your setup earlier.
    3. Ensure Grant Type is ‘Client Credentials’

  1. Click on Request Token button once setup is done, which should generate a new Access Token to use
  2. Select the newly generated token and click on Use Token on right hand pan.
  3. Send request and examine result

Postman is fantastic utility for developing and testing APIs. You can prove out all of your Web API based flow using Postman.

Recap

This blog discussed about how you can call Campus Nexus Web APIs by passing in OAuth 2.0 token and of course how you can generate OAuth 2.0 token. Following is where you can get 2 samples we talked about:

If you are interested in SSO between CMC Web Applications and your app, here are couple of previous blogs talking about that

-tushar

~tas

Leave a Reply

Skip to toolbar