OAuth2

In an attempt to support a more plug and play style authorization, the user register supports a subset of the OAuth2 protocol. Specifically it acts as an authorization server and supports the password and client_credentials grant types for issuing tokens (refer to OAuth2 RFC for more info).

Currently the following endpoints are available:

• https://installationroot/oauth2/token
• https://installationroot/oauth2/tokeninfo
• https://installationroot/oauth2/revoke

Security Note
Per the specification(OAuth2 RFC), all OAuth2 related requests should use HTTPs

There is no API for registering an application for an identifier and secret. This should be done "offline" in a manual procedure. Contact the paper running Infosoft, or if you are that paper contact Infosoft to register a new client.

Security Note

Please note that by implementing the OAuth2 protocol your application takes part in securing the users sensitive information. For instance your application should attempt to keep the refresh token secret if possible (i.e. don't store it in a clear text file or in a cookie). Please consider reading the specification on security consideration, Section 10 of the OAuth2 RFC on the responsibility of the client (your application)

In order to obtain a token a HTTP Post request must be issued to the token endpoint located at https://installationroot/oauth2/token. The request changes depending on the type of grant used. In any event all parameters should be application/x-www-form-urlencoded (basically what happens if you have a simple HTML form)

The full list of parameters that can/must be used when requesting a token

Password grant type

In the password grant type, the client knows (or asks) for the username and password and sends this to the authorization server along with its client id and secret.

Parameters needed when requesting a token:

• username

• password

• client_id

• client_secret

• grant_type (must be password)

• scope (optional)

POST /oauth2/token HTTP/1.1
Host: installationroot.infosoft.no
Content-Type: application/x-www-form-urlencoded
Content-Length: length

grant_type=password&client_id=MySimpleClient&client_secret=verySecret&username=john@doe.com&password=JohnsSecret&scope=something

The above should produce something like the following output

{
  "access_token":"AAEAAJMJt3jv5tNu74zACnWROKwjWq0ACUKFCH78BhDrfVC-SHORTENEDFORREADABILITY",
  "token_type":"bearer",
  "expires_in":3421,
  "refresh_token":"QE6q!IAAAADNYiW03M5-noGP1RobbSNKbBKCO2ngbvji54-SHORTENEDFORREADABILITY",
  "scope":"something"
}

Client Credentials grant type

In the Client credentials grant type, the client is trusted to maintain security and access to all users in a proper way. Thus no user information is required. All that is required is that the client application is pre-approved as a trusted application.

Parameters needed when requesting a token:

• client_id

• client_secret

• grant_type (must be client_credentials)

• scope (optional)

POST /oauth2/token HTTP/1.1
Host: installationroot.infosoft.no
Content-Type: application/x-www-form-urlencoded
Content-Length: length

grant_type=client_credentials&client_id=MySimpleClient&client_secret=verySecret&scope=something

The above should produce something like the following output

{
  "access_token":"AAEAAJMJt3jv5tNu74zACnWROKwjWq0ACUKFCH78BhDrfVC-SHORTENEDFORREADABILITY",
  "token_type":"bearer",
  "expires_in":3600,
  "refresh_token":"QE6q!IAAAADNYiW03M5-noGP1RobbSNKbBKCO2ngbvji54-SHORTENEDFORREADABILITY",
  "scope":"something"
}

Refresh token

The refresh token is a special grant type that allows the creation of a new access token without the need for user interaction if a refresh token has been granted previously.

Parameters needed when requesting a token:

• client_id

• client_secret

• grant_type (must be refresh_token)

• refresh_token

POST /oauth2/token HTTP/1.1
Host: installationroot.infosoft.no
Content-Type: application/x-www-form-urlencoded
Content-Length: length

grant_type=refresh_token&client_id=MySimpleClient&client_secret=verySecret&scope=something&refresh_token=QE6q!IAAAADNYiW03M5-noGP1RobbSNKbBKCO2ngbvji54-SHORTENEDFORREADABILITY

Once the application has obtained an access token, it might be useful to verify the information contained in it. By issuing a HTTP Get request the https://installationroot/oauth2/tokeninfo endpoint with the HTTP Authorization Header set to "Bearer ACCESSTOKENHERE", you can query the server for the following information.

• Client Identifier

• Seconds untill expiration

• Authorized scope

• Username

• Issue time (UTC)

• Associated Customer Number

In case the token has expired, is invalid, the authorization has been revoked or in short if anything is wrong, you will get an error saying that the token was invalid. If this is the case you should stop using it and request a new one.

{
  "client_identifier":"myAwesomeclient",
  "expires_in":"3568",
  "scope":["a scope", "anotherScope"],
  "user":"john@doe.com",
  "utc_issued":"2001-12-30T12:29:52Z",
  "customer_number":1001
}

Sometimes the user wants to revoke an authorization, for instance if you are sharing the session across multiple applications and the credentials have been invalidated. In order to do this a refresh token can be revoked by issuing a HTTP POST Request with the Authorization Header set to "Bearer ACCESSTOKENHERE".

In case you recieve an "invalid_token" error, the token is not valid, either because it has been tampered with or because it was already revoked, or simply because it is invalid!

In general if you receive an "invalid_token" error, then you should assume the token has expired or been revoked and request a new one. If you got the error using a refresh token, you have to obtain a new one. In all other cases there is probably something wrong with the service, please let us know by contacting Infosoft support. Don't display the error to the user, log it somewhere you can find it again along with the request that created the error.

{
  "Message":"An error has occurred.",
  "error":"invalid_token"
}

For all valid request types you should always get JSON back as the result, however when something is wrong you might get back XML as this is the default serialization format in the service. To avoid this you should add the HTTP Accept header with a value of application/json to all request. This way you should get JSON responses for everything

Other Resources