NorthStar Authentication

To access the NorthStar API from some environments, your application must use OAuth 2 authentication.

OAuth

OAuth 2 is an open authentication and authorization framework that orchestrates secure access to resources over HTTP. It delegates user authentication to the service that hosts the user account and grants authorization to specific third-party applications to access that account.

In the context of OAuth, the following terms are used as defined:

  • Resource.Information or functionality available through a RESTful API.

  • Client.The application requesting access on behalf of a user's account. Before it can get access, it must first be authorized by the user, and then the authorization must be validated by the API.

  • Resource owner.The user who authorizes an application to access their account.

  • Authorization server.Verifies the identity of the user, then issues access tokens to the application.

  • Resource server.Hosts the APIs and the protected user accounts.

You can find illustrations that show how OAuth works from different points of view. Here is a protocol flow illustration that may help NorthStar users who have no prior experience provisioning OAuth:

OAuth Protocol Flow

The NorthStar REST interface is the Authorization Server and Resource Server in the above illustration. The NorthStar Controller's administrator web interface is available for managing NorthStar users.

NorthStar Authentication API

Gets an authentication token that permits access to the NorthStar REST API. The token can be used in HTTP headers for subsequent RESTful requests for a period of time that you can set.

POST
oauth2/token
Authenticate

Authenticates and generates a token.

 

The Auth API is the entry point to all service APIs. To access the Auth API, you must know its URL.

Each request to NorthStar API requires the Bearer Authorization header. Clients obtain this token, along with the URL to other service APIs, by first authenticating against this URL with valid credentials.

The deployment determines how long expired tokens are stored. For example:

curl -u ${username}:${password} -X POST -k -H "Content-Type: application/json" -d '{"grant_type":"password","username":"'${username}'","password":"'${password}'"}' https://northstar.example.net:8443/oauth2/token returns the following: { "access_token": "zRApShiOxoCcBiFGPRhISKAbaUACWQBRqMPmaq40/NU=","token_type": "Bearer"}. Any subsequent assess should have the following HTTP header set: "Authorization: 'Bearer zRApShiOxoCcBiFGPRhISKAbaUACWQBRqMPmaq40/NU='" set.

Normal response codes
200
Request parameters
Parameter Style Type Description
grant_type query String
username query String
password query String
Request example: 
 {"grant_type":"password","username":"admin","password":"myNewAdminPassword"}
Response example: 
{ "access_token": "zRApShiOxoCcBiFGPRhISKAbaUACWQBRqMPmaq40/NU=","token_type": "Bearer"}