-
-
Notifications
You must be signed in to change notification settings - Fork 3
HSLynk Platform OAUTH documentation
HSLynk Platform uses OAuth 2.0 open-standard protocol to allow a user to authorize a Trusted App (aka client) to access data stored in the HSLynk, after he/she has been authenticated (logged-in).
A third-party application or a Trusted App (aka client) often requires limited access to a user's data stored in the HSLynk platform. To ensure that access to data stored in the HSLynk is not abused, all requests for access must be approved by the user.
OAuth 2.0 is a relatively simple protocol and a developer can integrate with HSLynk Platform's OAuth 2.0 endpoints without too much effort. In a nutshell, a Trusted App developer registers his/her application (aka client) with HSLynk, redirects a browser to a URL, parses a token from the response, and uses the token to invoke a HSLynk API. HSLynk Platform supports the OAuth 2.0 protocol with bearer tokens for web and native (aka installed) applications.
Trusted Apps (aka Clients) follow the same basic steps when accessing a HSLynk API using OAuth 2.0. At a high level, using OAuth 2.0 to access a HSLynk API consists of the following four steps:
All Trusted Apps (aka clients) that access a HSLynk API must be registered. The result of this registration process is a set of values (e.g. client_id, client_secret, redirect_uri, list of APIs to be accessed, etc.) that are known to both HSLynk and the Trusted App. The set of values needed varies based on the type of application being built. For example a JavaScript application does not require a secret, but a server-side web application or a native application does. To register as a Trusted App developer, please create an account at HSLynk Developer Network and follow the steps as guided.
Before a Trusted App (aka client) can access HSLynk APIs, it must obtain an access token that grants access to the APIs. There are several ways to make this request, and they vary based on the type of Trusted App. The request requires the user to login to HSLynk. After logging in, the user will see the permissions (list of APIs to be accessed) requested by the application and is asked if he/she is willing to grant the application those permissions. This process is called "user consent".
If the user grants permission to the Trusted App, the Trusted App will be sent an access token or an authorization code (which is used to obtain an access token). If the user does not grant permission to the application, the HSLynk Authorization Service returns an error.
After the Trusted App (aka client) has obtained an access token, it may send the access token in a request to a HSLynk API. The Access token is sent to a HSLynk API in the HTTP Authorization header as shown below.
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Access tokens have a limited lifetime and, in some cases, an application (aka client) needs access to HSLynk APIs beyond the lifetime of a single access token. When this is the case, the application can obtain what is called a refresh token. A refresh token allows the application to obtain new access tokens.
HSLynk Platform supports the following OAuth 2.0 authorization flows:
** Authorization Code Grant Flow Server-Side Web Applications and Native Applications (i.e. iPhone / iPad apps, Android apps) should use this flow.**
Server-Side Web Applications and Native Applications (i.e. iPhone / iPad apps, Android apps) should use this flow. Step (A): The Trusted App (aka client) initiates this flow by directing user's browser to HSLynk's authorization endpoint URL. The Trusted App (aka client) includes its client identifier, local state, and a redirection URI to which the HSLynk authorization service will send the browser back once access is granted (or denied).
In order for a Trusted App (aka client) to be approved, it must implement the OAuth workflow by launching the mobile device's default browser, external to the application. (The use of an embedded browser is not acceptable.) Step (B): The HSLynk authorization service authenticates the user (via the browser). After authentication (logging in), the user will see the permissions (list of APIs to be accessed) requested by the application and is asked if he/she is willing to grant the application those permissions. (Consent process)
Step (C): Assuming the user grants access, the HSLynk authorization service redirects the browser back to the Trusted App (aka client) using the redirection URI provided earlier. The redirection URI includes an authorization code and any local state provided by the application (aka client) earlier.
Step (D): The Trusted App (aka client) requests an access token from the HSLynk's token endpoint by including the authorization code received in the previous step. When making the request, the Trusted App (aka client) authenticates with the HSLynk authorization service by including its credential (i.e. client_id and client_secret). The Trusted App (aka client) also includes the redirection URI used to obtain the authorization code for verification.
Step (E): The HSLynk authorization service authenticates the Trusted App (aka client), validates the authorization code, and ensures the redirection URI received matches the URI used to redirect the application (aka client) in step (C). If valid, the HSLynk authorization service responds back with an access token and optionally, a refresh token. If a refresh token is present in the response, then the application (aka client) may use it to obtain new access tokens at any time.
The application (aka client) can invoke/access a HSLynk API after it receives the access token.
The application (aka client) initiates this flow by directing user's browser to HSLynk's authorization endpoint URL with a set of query string parameters.
In order for a Trusted App (aka client) to be approved, it must implement the OAuth workflow by launching the device's default browser, external to the Trusted App. (The use of an embedded browser is not acceptable.)
The set of query string parameters supported by the HSLynk authorization service for Authorization Code Grant Flow are:
An example URL is shown below.
https://www.hslynk.com/hmis-authorization-service/rest/authorize? response_type=code &trustedApp_id=YOUR_TRUSTED_APP_ID &redirect_uri=YOUR_REDIRECT_URI &access_type=VALUE_FOR_ACCESS_TYPE &approval_prompt=VALUE_FOR_APPROVAL_PROMPT &state=SOME_ARBITRARY_BUT_UNIQUE_STRING
For security, the value of redirect_uri parameter must exactly match one of the values registered during the Trusted App (aka client) registration process (including the http or https schemes, case, and trailing '/'). The state parameter should be set to some arbitrary string you generate uniquely for each auth request. This value will be passed back as a parameter to the redirect_uri once the user has authorized the Trusted App (aka client) and the Trusted App should check that the returned value matched the value it passed in at the start of the flow. This guards against Cross-site Request Forgery by ensuring the incoming redirect is part of the auth flow initiated by the Trusted App (aka client).
If the user is not logged-in into HSLynk, He/She will be prompted (via the browser) to log-in.
If the user has not already authorized the Trusted App, He/She will be prompted (via the browser) to authorize the Trusted App. This process is called "user consent".
If the user grants the access request, the HSLynk authorization service issues an authorization code and delivers it to the Trusted App (aka client) by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format:
(TABLE)
For example, the HSLynk authorization service redirects the browser by sending the following HTTP response:
HTTP/1.1 302 Found Location: YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE_GENERATED_BY_HSLynk_LYNK&state=YOUR_STATE_VALUE
In future, additional parameters/fields may be included in the response. The client must be coded to ignore the parameters/fields it does not recognize.
If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the HSLynk authorization service will inform the user of the error, and will not automatically redirect the browser to the invalid redirection URI.
If the user denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, the HSLynk authorization service informs the Trusted App (aka client) by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format:
(TABLE) For example, the HSLynk authorization service redirects the browser by sending the following HTTP response:
HTTP/1.1 302 Found Location: YOUR_REDIRECT_URI?error=ERROR_CODE_RETURNED_BY_HSLynk_LYNK&state=YOUR_STATE_VALUE
1.4 Exchange the authorization code for an access token
After the Trusted App (aka client) receives the authorization code, it should make an HTTPs POST request to HSLynk's token endpoint to exchange the authorization code for an access token and a refresh token.
The Trusted App (aka client) makes a request to HSLynk's token endpoint by adding the following parameters using the "application/x-www-form-urlencoded" format in the HTTP request entity-body:
(TABLE) The Trusted App (aka client) must specify its credentials (i.e. client id/client secret issued during Trusted App/client registration) using HTTP Basic authentication scheme as defined in RFC2617. The client identifier is used as the username, and the client secret is used as the password.
An example request
POST hmis-authorization-service/rest/token HTTP/1.1 Host: www.hslynk.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Accept: application/json grant_type=authorization_code& code=AUTHORIZATION_CODE_GENERATED_BY_HSLynk_LYNK& redirect_uri=YOUR_REDIRECT_URI
If the access token request is valid and authorized, the HSLynk authorization service issues an access token and optional refresh token, and constructs the response by adding the following parameters to the entity body of the HTTP response with a 200 (OK) status code:
(TABLE) The parameters are included in the entity body of the HTTP response using the "application/json" media type as defined by RFC4627. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.
The HSLynk authorization service includes the HTTP "Cache-Control" response header field RFC2616 with a value of "no-store" as well as the "Pragma" response header field RFC2616 with a value of "no-cache".
An example successful response:
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"ACESS_TOKEN_GENERATED_BY_HSLynk_LYNK", "token_type":"Bearer", "expires_in":NUMBER_OF_SECONDS_UNTIL_ACCESS_TOKEN_EXPIRES, "refresh_token":"REFRESH_TOKEN_GENERATED_BY_HSLynk_LYNK" }
In future, additional parameters/fields may be included in the response. The client must be coded to ignore the parameters/fields it does not recognize.
If the request is invalid or application (aka client) authentication failed, the HSLynk authorization service responds with an HTTP 400 (Bad Request) status code and includes the following parameters with the response:
(TABLE) An example error response:
HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "error":"ERROR_CODE_RETURNED_BY_HSLynk_LYNK" }
After the application (aka client) has obtained an access token, the Trusted App can access a HSLynk API by including it in an Authorization: Bearer HTTP header as shown below:
Authorization: Bearer ACCESS_TOKEN_GOES_HERE
If the HSLynk authorization service issued a refresh token to the Trusted App (aka client), the Trusted App (aka client) can use the refresh token to obtain a new access token any time until the the refresh token is revoked. The Trusted App (aka client) makes an HTTPs POST request to HSLynk's token endpoint by adding the following parameters using the "application/x-www-form-urlencoded" format in the HTTP request entity-body:
(TABLE) The application (aka client) must specify its credentials (i.e. client id/client secret issued during client registration) using HTTP Basic authentication scheme as defined in RFC2617. The client identifier is used as the username, and the client secret is used as the password.
An example request:
POST hmis-authorization-service/rest/token HTTP/1.1 Host: www.hslynk.com Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW X-HSLynk-TrustedApp-Id : YOUR_TRUSTED_APP_ID Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Accept: application/json Accept-Charset: utf-8 grant_type=refresh_token& refresh_token=REFRESH_TOKEN_GENERATED_BY_HSLynk_LYNK
If the request is valid and authorized, the HSLynk authorization service issues an access token, and constructs the response by adding the following parameters to the entity body of the HTTP response with a 200 (OK) status code: (TABLE)
The parameters are included in the entity body of the HTTP response using the "application/json" media type as defined by RFC4627. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary.
The HSLynk authorization service includes the HTTP "Cache-Control" response header field RFC2616 with a value of "no-store" as well as the "Pragma" response header field RFC2616 with a value of "no-cache".
An example successful response:
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"ACESS_TOKEN_GENERATED_BY_HSLynk_LYNK", "token_type":"Bearer", "expires_in":NUMBER_OF_SECONDS_UNTIL_ACCESS_TOKEN_EXPIRES }
In future, additional parameters/fields may be included in the response. The client must be coded to ignore the parameters/fields it does not recognize.
If the request is invalid or application (aka client) authentication failed, the HSLynk authorization service responds with an HTTP 400 (Bad Request) status code and includes the following parameters with the response: (TABLE)
An example error response:
HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "error":"ERROR_CODE_RETURNED_BY_HSLynk_LYNK" }
An application (aka client) uses the HSLynk's revocation endpoint to revoke an access token or a refresh token (i.e. refresh token and all related access tokens).
Developers may use this feature when configuring a "Log Out" button in their application.
The application (aka client) makes a request to the HSLynk's revocation endpoint by adding "one" of following parameters using the "application/x-www-form-urlencoded" format in the HTTP request entity-body: (TABLE)
An example request for revoking an access token
POST hmis-authorization-service/rest/revoke HTTP/1.1 Host: www.hslynk.com Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Accept: application/json Accept-Charset: utf-8 access_token=ACCESS_TOKEN_GENERATED_BY_HSLynk_LYNK
An example request for revoking a refresh token:
POST hmis-authorization-service/rest/revoke HTTP/1.1 Host: www.hslynk.com Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Accept: application/json Accept-Charset: utf-8 refresh_token=REFRESH_TOKEN_GENERATED_BY_HSLynk_LYNK
The HSLynk authorization service indicates successful processing of the request by returning an HTTP status code 200 with the access/refresh token that has been revoked successfully.
An example response if the specified access token has been revoked successfully:
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"ACCESS_TOKEN_GENERATED_BY_HSLynk_LYNK" } An example response if the specified refresh token has been revoked successfully:
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "refresh_token":"REFRESH_TOKEN_GENERATED_BY_HSLynk_LYNK" }
In future, additional parameters/fields may be included in the response. The client must be coded to ignore the parameters/fields it does not recognize. For all error conditions, a status code 400 is used along with one of the following error responses.
(TABLE) An example error response:
HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "error":"ERROR_CODE_RETURNED_BY_HSLynk_LYNK" }