Oauth for Clients

Overview

SERMO allows partners to use OAuth 2 to authenticate their users against our membership of verified physicians. This document will explain how to use this service.

Example requests use cURL.

Prerequisites

SERMO will create an account for you. You'll need to provide:

Your company name
You company url
A link to your company logo
URLs that will act as redirects after authentication

SERMO will provide you with 2 tokens that will be used throughout this process: client id and secret.

Authenticating a User

Authenticating a user is a multi-step process.

First, you'll send the user to a url that will allow them to authorize your access. Allowed or denied, they'll be directed back to the redirect url provided.

If access is granted, you will get a authorization code as a get parameter on the return url. If access is not granted, you'll get an error parameter.

The authorization code is then used to get a long term token. This token will identify the relationship between us, you and the user. Please see Life of a Token to better understand how long the token is good for, and under what conditions it will no longer be valid.

Authenticating a user follows these steps:

Send them to a url, where the user can grant access
Get the authorization code from the return redirect
Use the short term token to request your long term access

Getting the authorization code

An authorization code is the first step in authentication. There is a specially crafted url that you must provide. The user will then allow or deny access. If they allow, you will receive a short term authorization token via a GET parameter in the redirect. If denied, you'll get an error message for the return GET parameter.

The link

To authenticate, send the user to a URL of this structure:

https://app.sermo.com/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=code

Parameters:

CLIENT_ID: This is the client ID provided by SERMO.
REDIRECT_URI: This is the redirect_uri you provided to SERMO. The value must be URL percent encoded to UTF-8 (URL % Encoding). http://example.com thus becomes http%3A%2F%2Fexample.com.

Be sure to include the response_type=code.

Markup

Below you'll find markup to produce a linked button for directing your users to single sign on. You will need to fill in the destination with the link constructed above.

<a href="[link from above]">
  <img src="http://developer.sermo.com/img/sermo-sso-btn.png" />
</a>

Outcomes

Success

If the user allows access, they will be redirected back to you with the authorization code as the GET parameter code. For example:

http://example.com/?code=9383723f07e1c62d3d81db84afd2ea3cb064fd2c72042c692636f932674bf267

Use that code to get the long term token for the user in the next step.

Failure

If the user denies authorization, they will be redirected back to you with the GET parameters error and error_description.

For example:

http://example.com/?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request`.

Getting the access token

You will need the authorization token from the previous step to gain the access token. The token you recieve from this step will be used for ongoing authorization checks and obtaining information about the user.

The request

The token must be requested via POST to oauth/token with your client id, secret, redirect uri and the authorization token from above.

The request should be made as a POST with a body that is application/x-www-form-urlencoded.

Here is an example in curl:

 curl -F grant_type=authorization_code \
   -F client_id=<CLIENT_ID> \
   -F client_secret=<SECRET> \
   -F code=<AUTHORIZATION_CODE> \
   -F redirect_uri=<REDIRECT_URI> \
   -X POST https://app.sermo.com/oauth/token

CLIENT_ID: the client id provided by SERMO
SECRET: the secret token provided by SERMO
REDIRECT_URI: the redirect uri provided to SERMO
AUTHORIZATION_CODE: the code gleaned from the previous step

Outcomes from requesting access

The example responses below are JSON. Multiple requests will result in failure, as the authorization token will be expired upon usage.

Success

{
  "access_token": "1f0af717251950dbd4d73154fdf0a474a5c5119adad999683f5b450c460726aa",
  "token_type": "bearer",
  "expires_in": 7200
}

access_token: : This is the access token you will use for verifying authentication (token checking) and getting user information. token_type: : bearer. This will always be the case. expires_in: : Seconds until this token expires. Null means no expiration.

Failure

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid,
                        expired, revoked, does not match the redirection URI used in the
                        authorization request, or was issued to another client."
}

Token Checking

The API allows clients to verify the validity of a user token that was previously provided by the OAuth API. This may be used by client applications to verify that a user was not deactivated during the lifetime of the token.

It is worth noting that a user changing their password in SERMO will result in an expired token. Tokens will be invalid if the user account has been deactivated.

Request format

A GET request with the proper header must be made.

URL: https://app.sermo.com/user/oauth/token/info
HEADER:
```
Authorization: Bearer <ACCESS_TOKEN>
```
ACCESS_TOKEN: The long term access token recieved when requesting access. Please note, it must be provided in the header.

An example curl request:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://app.sermo.com/oauth/token/info

Responses

Token is good/active

The user is still an active SERMO member, and the token has not been expired or revoked.

{
  "resource_owner_id": 123,
  "scopes": [],
  "expires_in_seconds": 6881,
  "application": {
    "uid": "c60e23cff405e83f62d4e8fb5777788e773ffd04e3ae690b747c6d022b9cb7e8"
  }
}

resource_owner_id: ID of SERMO user
scopes: access grants you have for gaining user information
expires_in_seconds: remaining lifetime of the checked token
application.uid: This should match your CLIENT_ID

Token is unknown or not valid

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter,
                        includes an unsupported parameter value, or is
                        otherwise malformed."
}

User is inactive

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter,
                        includes an unsupported parameter value, or is
                        otherwise malformed."
}

Recommendations for when to check

We suggest that you verify access tokens periodically to ensure the user is still active within SERMO, and that they still agree to allow you access.

Retrieve User Information

The API allows clients to retrieve information about a user with the long term user token.

Request format

A GET request with the proper header must be made.

URL: https://app.sermo.com/user/oauth/user/info
HEADER:
```
Authorization: Bearer <ACCESS_TOKEN>
```
ACCESS_TOKEN: The long term access token recieved when requesting access. Please note, it must be provided in the header.

An example curl request:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://app.sermo.com/oauth/user/info

Responses

Token is good/active

The user is still an active SERMO member, and the token has not been expired or revoked.

{
  "first_name": "Elizabeth",
  "last_name": "Blackwell",
  "country_of_practice": "US",
  "primary_specialty": "Obstetrics & Gynecology"
}

Token is unknown, not valid, or inactive

The call will return the status 401 Unauthorized. It will also include headers:

error="invalid_token"
error_description="The access token is invalid"

Life of a Token

Authorization token

Authorization tokens are by nature short lived. We will automatically expire them after \<look it up> minutes.

Each time a user allows access, a new token is generated and the old one expired. Thus, if they keep going back to the link you provide, only the last redirect back will have the active token.

Access token

Access tokens have a more complex life cycle than their authorization counterparts. The default lifetime is dictated by your agreement with SERMO. There are also a number of events they will cause this token to expire.

The user changes password in SERMO
The user is marked inactive in SERMO
Your client account expires
Your client account has its expiration length altered
The user revokes your access