How to access the RamBase API Roger Gullhaug

How to access the
RamBase API
Roger Gullhaug
This document describes how to get an acces token which
will allow an application to access the RamBase API on a
user’s behalf.
Jakob HattelandComputer
Raglamyr
4/18/2012
Contents
Introduction ........................................................................................................................................ 2
Overview of the different authorization flows ....................................................................... 2
Getting access to RamBase API .................................................................................................. 3
Server-side web application flow ................................................................................................ 3
Client-side web application flow ................................................................................................. 7
Resource Owner Password Flow ................................................................................................. 9
Client Credentials Flow ................................................................................................................. 11
Two-factor authentication ........................................................................................................... 12
Calling the Rambase API.............................................................................................................. 13
Refreshing an access token ........................................................................................................ 14
Native applications ......................................................................................................................... 15
Customer login (CNT login) ........................................................................................................ 16
Introduction
The RamBase API is secured using the OAuth 2.0 standard. Only registered
clients can access the API. Depending on the application being built there will be
different authentication flows to choose between.
This Oauth 2.0 implementation is based on the Oauth 2.0 specification version
25. The specification can be found here:
http://tools.ietf.org/html/draft-ietf-oauth-v2-25
Since we use a standardized way of securing the API you can connect using
standard Oauth 2.0 client libraries. This document describes how to connect if
you do not use a client library.
The RamBase API uses two-factor authentication where possible.
Overview of the different authorization flows
There are 4 different authorization flows you can choose between. That does not mean that you can
pick the one you like the best, but depending on the type of application you are building we will
together agree on the appropriate application flow for your application. You can find a quick
overview of the different authorization flows below:
Server-side web application flow. This flow is used when the client is a web application server. Client
secret and refresh token should never be leaked to the browser (or native client) where the user may
have access to it. When a client log in on the login page provided by RamBase you get an
authorization code which needs to be exchanged for an access token. Another name of this flow is
Authorization code flow. You can use this flow even if your application is not a server-side web
application if the application uses a backend which is a server-side application.
Client-side web application flow. This flow is also called Implicit Grant Flow. It should be used when
only temporary access to data is required. The oauth client is running in the browser (using
javascript/flash/silverlight). Refresh token’s is not allowed in this flow, but we support sliding
expiration of the access token. When you use this flow you don't get an authorization code, and you
don't have a client-secret.
Resource owner password flow. When using this flow you are exchanging the username/password
with an access token directly. Because the resource owner's password is exposed to the application,
this flow should be used sparingly. It is recommended only for first-party "official" applications
released by the API provider (JHC), and not open to wider third-party developer communities.
Refresh token is not allowed, but we support sliding expiration.
Client Credentials flow. This flow is used when the client is acting on behalf of the app itself.
Typically a server login. Client id and client secret is exchanged for an access token. It is extremely
critical that the client secret and access token is kept highly confidential. Refresh tokens is not
supported. If the access token expires the server will ask for a new access token directly without
using a refresh token.
Getting access to RamBase API
To be able to access the RamBase API you need to register your application with
Hatteland Computer. We will need to know the following about your application.
Name of application
Who is responsible for the application
Type of application (server side web app/client side web app/mobile
app/windows app)
For web applications you need to provide a redirect_uri that your application
uses. When the user grants access (or denies) the RamBase authorization server
will redirect to this uri.
When you have registered the application with JHC you will be provided a
client_id. Depending on the type of application you are developing you will
maybe also retrieve a client_secret.
Server-side web application flow
This flow is designed for web applications with servers that can store information
and maintain state. While this section walks through the steps your code would
go through to use OAuth 2.0 in a server-side web application, you could also use
one of several client libraries in your OAuth 2.0 implementation.
The following steps explain the server-side flow:
Getting an access token
1. When a user first tries to perform an action that requires API
authentication, direct the user to RamBase's authorization server at
https://api.rambase.com/oauth2. The authorization server will refuse
HTTP connections because it is only accessible over SSL (HTTPS). It
supports the following URL parameters:
Parameter
Description
client_id
Required. The OAuth 2.0 client ID for your
application. Hatteland Computer will give you this
when you register your application as a client
redirect_uri
Required. A registered redirect_uri for that client ID.
response_type
Required. Set this parameter's value to code
state
Any string that your application would use to maintain
state between the request and redirect response. Your
application will receive the same value that it sends for
this parameter. For example, you could use this
parameter to redirect the user to a particular resource
in your application
The sample URL below shows a redirect to RamBase authorization server for
an application requesting permission to submit YouTube Data API requests on
the user's behalf:
https://api.rambase.net/oauth2?
client_id=yO6wK-6abcKlRHh2L7HtWw1&
state=T_nCih9WAEy_0-Ir4XoyPw2&
response_type=code&
redirect_uri=https://www.myapp.com/auth2callback
2. RamBase authorization server will display the name of your application
and the RamBase services that it is requesting permission to access on the
user's behalf. The user can then consent or refuse to grant access to your
application.
3. After the user consents or refuses to grant access to your application,
RamBase will redirect the user to the redirect_uri that you specified in step
1.
o
If the user granted access to your application, RamBase will have
appended a code parameter to the redirect_uri. This value is a temporary
authorization code that you can exchange for an access token as discussed
in step 4.
http://localhost/oauth2callback?code=4/ux5gNj_mIu4DOD_gNZdjX9EtOFf
o
If the user refused to grant access to your application, RamBase will have
included the access_denied error message in the hash fragment of the
redirect_uri:
http://localhost/oauth2callback#error=access_denied
4. Assuming the user has granted access to your application, exchange the
authorization code obtained in step 3 for a refresh token and access token.
To do so, send a POST request to
https://api.rambase.net/oauth2/access_token that includes the following
key-value pairs in the request body:
Key
Value
code
Required. The authorization code that RamBase
returned to your redirect_uri in step 3.
client_id
Required .The OAuth 2.0 client ID for your
application.
client_secret
Required .The client secret associated with your
client ID.
redirect_uri
Required . A registered redirect_uri for your client
ID
grant_type
Required.Set this value to authorization_code.
A sample request is displayed below:
POST /oauth2/access_token HTTP/1.1
Host: api.rambase.net
Content-Type: application/x-www-form-urlencoded
code=23243_mIufsdfs33_djX9EtOFf&
client_id= yO6wK-6abcKlRHh2L7HtWw1&
client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
redirect_uri=http://localhost/oauth2callback&
grant_type=authorization_code
5. RamBase will respond to your POST request by returning a JSON
object that contains a short-lived access token and a refresh token.
1. {
"access_token" : "ya29.AHES6ZTtm7SuokEB-R",
"token_type" : "Bearer",
"expires_in" : 3600,
"refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3"
}
Your application should store both values. It’s very important to
keep the client_secret secret. It should therefore never be sent to
the client. The Calling the RamBase API section explains how to
submit an authorized request using the access token. The
Refreshing an access token section explains how to use the refresh
token to obtain a new access token if the one that you have expires.
Client-side web application flow
This flow is designed for JavaScript-based web applications that cannot
maintain state over time.
The following steps explain the client-side flow:
1. Getting an access token
When a user first tries to perform an action that requires API
authentication, direct the user to RamBase's authorization server at
https://api.rambase.net/oauth2. The authorization server will refuse
HTTP connections because it is only accessible over SSL (HTTPs). It
supports the following URL parameters:
Parameter
Description
client_id
Required. The OAuth 2.0 client ID for your
application. Hatteland Computer will give you this
when you register your application as a client
redirect_uri
Required. A registered redirect_uri for that client ID.
response_type
Required. Set this parameter's value to token
state
Any string that your application would use to maintain
state between the request and redirect response. Your
application will receive the same value that it sends for
this parameter. For example, you could use this
parameter to redirect the user to a particular resource
in your application
The sample URL below shows a redirect to RamBase's authorization
server for an application requesting permission to Rambase data on the
user's behalf:
1. https://api.rambase.net/oauth2?
client_id=1084945748469-g34imk572&
redirect_uri=http://localhost/oauth2callback&
response_type=token
2. RamBase's authorization server will display the name of your application and
the RamBase services that it is requesting permission to access on the user's
behalf. The user can then consent or refuse to grant access to your
application.
3. After the user consents or refuses to grant access to your application,
RamBase will redirect the user to the redirect_uri that you specified in step
1.
o
If the user granted access to your application, RamBase will have
appended a short-lived access token in the hash fragment of the
redirect URI. The response will also include the expires_in and
token_type parameters. These parameters describe the lifetime of the
token in seconds and the kind of token that is being returned,
respectively. Finally, the response will include the state parameter if
a state parameter was included in the original request to the
authorization server.
http://localhost/oauth2callback#access_token=34fd3dfwww3
2&token_type=Bearer&expires_in=3600
JavaScript code running on your page can capture the access token
from the window.location.hash value and either store the token in a
cookie or POST it to a server.
o
If the user refused to grant access to your application, RamBase will
have included the access_denied error message in the hash fragment
of the redirect_uri:
http://localhost/oauth2callback#error=access_denied
Resource Owner Password Flow
Because the resource owner’s password is exposed to the application, this flow
should be used sparingly. It is recommended only for first-party “official”
applications released by JHC. If this flow is used to access a customer’s resources
(CNT) it would be OK to use this flow also for third-party applications.
In this flow the client itself ask the user for their username and password. The
application then makes either a client side or server side request to the RamBase
authorization server. If the username and password is correct you will get back
an access token.
The following steps explains the resource owner password flow:
1. Getting an access token
When a user has entered his username and password you should make
a POST request to the RamBase authorization server at
https://api.rambase.net/oauth2/access_token. The authorization server
will refuse HTTP connections because it is only accessible over SSL
(HTTPs). You should provide the following parameters:
Key
Value
client_id
Required .The OAuth 2.0 client ID for your
application.
client_secret
Required .The client secret associated with your
client ID.
username
Required . The username entered by the user
Password
Required. The password entered by the user
grant_type
Required.Set this value to password.
target
Optional. This is in most cases optional. Use this
parameter to specify RamBase target (eg. RIC, SQLRIC,
RESRIC…) If not provided and the user only have access
to one target, the target will be automatically set. If the
user has access to multiple targets, you will get 401
Unauthorized and a list of allowed targets.
otp
Optional. If you login using pid and password you will
also need a “one time password” (OTP) if you are
outside a “safe zone”. The OTP number is sent as an
email or SMS to the user, when it is required.
endclientip
Optional. If you perform a login where you need to
forward the Ip address of the end user, this value will
override the client ip address. This will only be necessary
if the ip of the server differs from the ip of the end user.
This will only work if the host ip is within a trusted ip
range.
A sample request is displayed below:
POST /oauth2/access_token HTTP/1.1
Host: api.rambase.net
Content-Type: application/x-www-form-urlencoded
client_id= yO6wK-6abcKlRHh2L7HtWw1&
client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
username=4659&
password=so334DED33A&
grant_type=password
2. RamBase will respond to your POST request by returning a JSON
object that contains a short-lived access token and a refresh token.
2. {
"access_token" : "ya29.AHES6ZTtm7SuokEB-R",
"token_type" : "Bearer",
"expires_in" : 3600,
"refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3"
}
3. If the target is not specified and the user have access to multiple
targets, a list of the targets that the user have access to is returned.
3. {
"message" : "Please provide a valid target",
"allowed_targets" : "RIC,SQLRIC"
}
Client Credentials Flow
This flow should be used when the application is acting on behalf of the
application itself, and not on a specific user. This flow should not be used if the
client_secret cannot be kept 100% secret. Because of that you can never use
this from a client-side application.
The following steps explains the client credentials flow:
1. Getting an access token
The application needs to request an access token from the RamBase
authorization server, authenticating the request with its client
credentials. A POST request is sent to
https://api.rambase.net/oauth2/access_token. The authorization server
will refuse HTTP connections because it is only accessible over SSL
(HTTPs). You should provide the following parameters:
Key
Value
client_id
Required .The OAuth 2.0 client ID for your
application.
client_secret
Required .The client secret associated with your
client ID.
grant_type
Required.Set this value to client_credentials.
customerid
Optional. The customer you want this login to be
associated with.
supplierid
Optional. The supplier you want this login to be
associated with.
endclientip
Optional. If you perform a login where you need to
forward the Ip address of the end user, this value will
override the client ip address. This will only be
necessary if the ip of the server differs from the ip of
the end user. This will only work if the host ip is
within a trusted ip range.
A sample request is displayed below:
POST /oauth2/access_token HTTP/1.1
Host: api.rambase.net
Content-Type: application/x-www-form-urlencoded
client_id= yO6wK-6abcKlRHh2L7HtWw1&
client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
grant_type=client_credentials
2. RamBase will respond to your POST request by returning a JSON
object that contains a short-lived access token. You will not get a
refresh token. To obtain a new access token when the existing one
expires just go back to step 1 and request an access token in the
same way you did the first time.
4. {
"access_token" : "ya29.AHES6ZTtm7SuokEB-R",
"token_type" : "Bearer",
"expires_in" : 3600
}
Two-factor authentication
If a user is trying to login within a “trusted” zone, where no OTP is required, the login can be done in
one single POST request with no need for two-factor authentication. This requires that the Target is
specified or that the user only have access to one Target, in which case it will automatically try to
login in to said Target.
If the user is trying to login outside a “trusted” zone, where an OTP is required, the following result
will be returned to notify the application that OTP is required. When this is returned, an OTP has
been sent to the users mail address or by SMS.
5. {
"message " : "Please provide One Time Password",
"allowed_targets " : "SQL,SQLRIC",
"otp_required" : true
}
Calling the Rambase API
After obtaining an access token for a user, your application can use that token to
submit authorized API requests on that user's behalf. The API supports two ways
to specify an access token:
1. Specify the access token as the value of the access_token query
parameter:
https://api.rambase.net/sales/customers?access_token=ACCESS
_TOKEN
2. Specify the access token as the value of the Authorization: Bearer HTTP
request header:
1. GET /sales/customers HTTP/1.1
Host: api.rambase.net
Authorization: Bearer ACCESS_TOKEN
...
The API will return an HTTP 401 response code (Unauthorized) if you submit a
request to access a protected resource with an expired access token. The
following section explains how to refresh an access token
Refreshing an access token
If your application obtains a refresh token during the authorization process, then
you will need to periodically use that token to obtain a new, valid access token.
Server-side web applications, installed applications, and devices all obtain refresh
tokens.
At any time, your application can send a POST request to RamBase's
authorization server that specifies your client ID, your client secret, and the
refresh token for the user. The request should also set the grant_type parameter
value to refresh_token.
Parameter
Description
client_id
Required. The OAuth 2.0 client ID for your
application. Hatteland Computer will give you this
when you register your application as a client
client_secret
Required. The secret you got from JHC when you
registered the application.
grant_type
Required. Set this parameter's value to
refresh_token
refresh_token
Required. The refresh token key you obtained during
the authorization process.
The following example demonstrates this request:
POST /oauth2/access_token HTTP/1.1
Host: api.rambase.net
Content-Type: application/x-www-form-urlencoded
client_id= yO6wK-6abcKlRHh2L7HtWw1&
client_secret=qeehXh1SlUNgvyWGwDk1Edd&
refresh_token=336BMfW9j53gdGImsixUH6kU5RsR4z&
grant_type=refresh_token
The authorization server will return a JSON object that contains a new access
token:
6. {
"access_token" : "HES6ZTtm7SuokEB-R",
"token_type" : "Bearer",
"expires_in" : 3600
}
Native applications
If you create a native client application you can use the client-side web
application flow, but then you will only be given a short-lived access token and
no refresh token. This means that you will not be able to create an application
which allows the user to stay logged in for a long time.
It’s is extremely important that you don’t use the server-side web application
flow in a native application because there is no way you can keep the
client_secret secret for the user of your application. If your application requires
users to stay logged in for a long time you have to have a server side backend
for your application, and use server-side web application flow from the server
side.
A challenge with oauth in a native client is to show the login page which is html
based and needs to be displayed in a browser. A solution to this problem is to
embed a browser in your application. When you use the server side web
application flow you will need to register a redirect uri. This is the uri which will
be requested when the user accepts the login.
In a native app you don’t have a web server you can redirect to. In this case
there is a special redirect uri you can use urn:ietf:wg:oauth:2.0:oob. If you
use the callback uri the RamBase api will redirect the browser to a new page
where the authorization code is displayed. This page will instruct the user to copy
this code and paste it into your application. If you don’t want to have any manual
interaction with the user the authorization code is also displayed in the title of
the page like this Success code=dfdse43434fd532fdfsd23442342. Your
application can then parse this code from the title automatically and the close the
page without showing it to the user.
When you have the code you can send it to the server side backend which will in
the next turn send it to the RamBase authorization server to exchanging it for an
Access token.
Customer login (CNT login)
If you would like a customer to be able to login to the API you should specify that
your client uses the Client Credentials flow.
To login you will then first login using the Client Credentials Flow. You then
provide a server pid/password. In return you will get a json containing an access
token and a rambase_sid.
You can then login the customer using the Password credential flow. You then
need to set is_cnt_login to true and provide the rambase_sid you got in response
from the Client Credentials flow.