Using OAuth 2.0 to Access ionbiz APIs

Transcription

1 Using OAuth 2.0 to Access ionbiz APIs ionbiz APIs use the OAuth 2.0 protocol for authentication and authorization. ionbiz supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side applications. OAuth 2.0 is a relatively simple protocol. To begin, you obtain OAuth 2.0 credentials from the Applications page inside ionbiz site. Then your client application requests an access token from the ionbiz Authorization Server, extracts a token from the response, and sends the token to the ionbiz API that you want to access. This page gives an overview of the OAuth 2.0 authorization scenarios that ionbiz supports, and provides links to more detailed content. Note: Given the security implications of getting the implementation correct, we strongly encourage you to use OAuth 2.0 libraries when interacting with ionbiz's OAuth 2.0 endpoints. It is a best practice to use well-debugged code provided by others, and it will help you protect yourself and your users. For more information, see Client libraries. Basic steps All applications follow a basic pattern when accessing a ionbiz API using OAuth 2.0. At a high level, you follow four steps: 1. Obtain OAuth 2.0 credentials from the ionbiz site. Visit the Application page from ionbiz site to obtain OAuth 2.0 credentials such as a client ID and client SECRET that are known to both ionbiz and your application. The set of values varies based on what type of application you are building. For example, a JavaScript application does not require a secret, but a web server application does. 2. Obtain an access token from the ionbiz Authorization Server. Before your application can access private data using a ionbiz API, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple APIs. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

2 There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application might request an access token using a browser redirect to ionbiz, while an application installed on a device that has no browser uses web service requests. Some requests require an authentication step where the user logs in with their ionbiz account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent. If the user grants the permission, the ionbiz Authorization Server sends your application an access token (or an authorization code that your application can use to obtain an access token). If the user does not grant the permission, the server returns an error. 3. Send the access token to an API. After an application obtains an access token, it sends the token to a ionbiz API in an HTTP authorization header. It is possible to send tokens as URI query-string parameters, but we don't recommend it, because URI parameters can end up in log files that are not completely secure. Also, it is good REST practice to avoid creating unnecessary URI parameter names. Access tokens are valid only for the set of operations and resources described in the scope of the token request. For example, if an access token is issued for the ionbiz Resources API, it does not grant access to the ionbiz Projects API. 4. Refresh the access token, if necessary. Access tokens have limited lifetimes. If your application needs access to a ionbiz API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens. Note: Save refresh tokens in secure long-term storage and continue to use them as long as they remain valid. Limits apply to the number of refresh tokens that are issued per client-user combination, and per user across all clients, and these limits are different. If your application requests enough refresh tokens to go over one of the limits, older refresh tokens stop working.

3 Scenarios A. Service accounts Your application can authenticate using the client_id and secret. In these situations your application needs to prove its own identity to the API, but no user consent is necessary. Similarly, in enterprise scenarios, your application can request delegated access to some resources. For these types of server-to-server interactions you need a service account, which is an account that belongs to your application instead of to an individual end-user. Your application calls ionbiz APIs on behalf of the service account, and user consent is not required. (In non-service-account scenarios, your application calls ionbiz APIs on behalf of end-users, and user consent is sometimes required.) Note: These service-account scenarios require applications to create and encode the client_id and secret. We strongly encourage you to use a library to perform these tasks. If you write this code without using a library, you might make errors that would have a severe impact on the security of your application. For a list of libraries that support this scenario, see the OAuth 2.0 site. A service account's credentials, which you obtain from the ionbiz site, a client ID and a client secret. You use the client ID and secret to create the token request. Your application then sends the token request to the ionbiz OAuth 2.0 Authorization Server, which returns an access token. The application uses the token to access a ionbiz API. When the token expires, the application repeats the process.

4 Example access token request POST HTTP/1.1 Host: localhost:1186 Content-Length: 93 User-Agent: Fidler Content-Type: application/x-www-form-urlencoded scope=r_resource&grant_type=client_credentials&client_id=={client_id}&client_secret={client_se cret}&state=anystate r_resource->read resources Example Result HTTP/ OK Status: 200 OK Content-Type: application/json; charset=utf-8... Content-Encoding: gzip Content-Length: 140 {"token_type":"bearer","access_token":"aaaa%2faaa%3da","expires_in":"28800"} B. Web server applications The ionbiz OAuth 2.0 endpoint supports web server applications that use languages and frameworks such as PHP, Java, Python, Ruby, and ASP.NET. The authorization sequence begins when your application redirects a browser to a ionbiz URL; the URL includes query parameters that indicate the type of access being requested. ionbiz handles the user authentication, session selection, and user consent. The result is an authorization code, which the application can exchange for an access token and a refresh token. The application should store the refresh token for future use and use the access token to access a ionbiz API. Once the access token expires, the application uses the refresh token to obtain a new one.

5 Flow example: 1. Authorization code request The web application redirects a browser to an authorization code end point with a set of query parameters, which are required by an authorization server. The parameters response_type,client_id, redirect_uri and scope must be present. And state is an optional parameter. Response_type must have value code. Client_id is the identifier of the calling client. Redirect_uri is the URI to which the user agent will be redirected within the authorization response message. This URI must be same as the URI, which registered by the client at the authorization server. Scope contains which resources requested by this client (separated by space). State is normally used by the client to maintain state between request and callback. An example URL is shown below. response_type=code& client_id=oauth_client& redirect_uri= scope=r_project& state=anystate 2. Authorization code response If the user allows the access, a response containing an authorization code and the state parameter (if included in the request) will be sent to the redirect_uri as specified in the request. If the user decline the request, an error message will be sent back.

6 A successful response: ystate An error response: 3. Access token request After the client receives the authorization code, it is able to create access token request. This request is an HTTPs POST request, and must contain parameters: grant_type, code, andredirect_uri in the HTTP body. Grant_type must have authorization_code as value. The received authorization code is set as value into the parameter code. Reditect_uri is the URI, which the client used to get the access token response. This URI must be same as the originally redirect_uri within the authorization request. For authentication the client, it must include its client credentials (client_id and client_secret) in the HTTP header of the reqeust as authorization header. And the request should use application/x-www-form-urlencoded for Content-type in the request, which is included in the HTTP header. Example request: https POST HTTP/1.1 Authorization: Basic TE... Content-type: application/x-www-form-urlencoded grant_type=authorization_code& code=aby-pywahukq_mbk9cxbyv8bedkb9az1qzkupbs84fq4phkh& redirect_uri= 4. Access token response The authorization server will build a JSON formatted access token response including the parameters access_token, token_type, expires_in and scope after successful validating the access token request. A successful access token response example: HTTP/ OK Content-Type: application/json;charset=utf-8 Cache-Control: no-store Pragma: no-cache { } "access_token":"a...", "token_type":"bearer", "expires_in":"3600", "scope":"r_project"

7 Token expiration You should write your code to anticipate the possibility that a granted token might no longer work. A token might stop working for one of these reasons: The user has revoked access. The expiration period elapses Make an API call With a valid access token in hand, you're ready to make a request to a REST interface. Below is call to get all resources from ionbiz. The simple request uses only the required input fields. The access token is an OAuth bearer token, and is included in the header of your requests with the following syntax: Authorization: Bearer <Access-Token>. Important: You must supply a valid access token to complete this request (generate a valid token using the example call above). Example ionbiz get all resources request GET /api/resources/getlist Host: Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA%2FAAAAAAAAAAAA A fully list of REST API operations and their signatures can be checked under API reference page (ionbizsite/apis-explorer) Examples:

8 resources: create, update, delete and view GET /api/resources/get/{id} GET /api/resources/getlist PUT /api/resources/update POST /api/resources/add DELETE /api/resources/delete/{id} projects: create, update, delete and view GET /api/projects/get/{id} GET /api/projects/getlist PUT /api/projects/update POST /api/projects/add DELETE /api/projects/delete/{id}