NorthStar authentication

You can use the NorthStar APIs within different enviroments. In some cases you will need to provide authentication for applications to access NorthStar functionality. For this purpose, NorthStar uses OAuth 2.

OAuth

OAuth 2 is an open authentication and authorization framework that orchestrates secure access to resources over HTTP. It works by delegating user authentication to the service that hosts the user account, and granting 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 avaialable 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 we think will help NorthStar users who have no prior experience provisioning OAuth:

OAuth protocol flow

NorthStar REST interface is the Authorization Server and Resource server in the above illustration. 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 services 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"}