Security API Documentation

Contents

OAuth Authentication API

  1. Client credentials authentication
  2. Email and password institution authentication
  3. Institution IP address authentication
  4. Referrer URL institution authentication
  5. Geo-location institution authentication
  6. Library card institution authentication
  7. Shibboleth institution authentication

Application API

  1. Get Application By Key

Institution API

  1. Authenticate institution by Shibboleth

Interaction with other API services


OAuth Authentication API

Security Facade uses OAuth to secure access to API services. First, client should be authenticated and get access token from Security API using authorization grant. After that access token is passed in each request to specific API service via Security Facade. Access token has pre-configured expiration time and it becomes invalid after expired. To get new access token client should use refresh token which has longer lifetime or authenticate again and get new access + refresh token pair.

Currently following authorization grants are supported:

  1. Client Credentials Grant (see http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-1.3.4 and http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.4)
    Trusted clients are authenticated using their own credentials without need to have any institution credentials and have access to allowed API services.
  2. Resource Owner Credentials Grant (see http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-1.3.3 and http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.3)
    Clients are authenticated using their own credentials and are passing institution authentication using one of following methods:
    1. By institution Email and password
    2. By institution IP address
    3. By referrer
    4. By institution geo-location
    5. By library card
    6. Shibboleth authentication
    This way client will have both client authentication and specific institution authentication. Currently access to API services and data is not restricted depending on institution authentication. If client authenticated with any institution credentials - it will have access to all institutions data. Data access is restricted by client itself through passing necessary institutionId to API.


Client Credentials Authentication

Client sends its credentials (client ID + key) to security API and get access + refresh token pair back.

URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=client_credentials

HTTP Method
GET POST

Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=client_credentials
JSON response returned in case of successful authentication will be in following format:

{
    "access_token": "0929676d-5308-4152-8384-fdca51e1c1c2",
    "expires_in": 1799,
    "refresh_token": "c68c3a66-0b38-40a0-a975-4fef9f4c5844",
    "token_type": "bearer"
}
        

Email and Password Institution Authentication

Client sends its credentials along with institution email and password credentials to security API and get access + refresh token pair back.

URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=email_password&email=$email&password=$password

HTTP Method
GET POST

Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=email_password&email=admin@xdev.internal.test&password=devx


IP Address Institution Authentication

Client sends its credentials along with institution IP address to security API and get access + refresh token pair back. If institutionId is specified, it is checked to match IP address. In case of mismatch authentication is failed.

URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=ip&ip=$ip_address
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=ip&ip=$ip_address&institutionId=$instituionId

HTTP Method
GET POST

Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=ip&ip=158.152.152.121
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=ip&ip=158.152.152.121&institutionId=38


Referrer Institution Authentication

Client sends its credentials along with referrer URL to security API and get access + refresh token pair back. If institutionId is specified, it is checked to match referrer URL. In case of mismatch authentication is failed.

URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=referrer&referrer=$referrer_url
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=referrer&referrer=$referrer_url&institutionId=7172

HTTP Method
GET POST

Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=referrer&referrer=http%3A%2F%2Flalibcon.state.lib.la.us%2Fredirect.php%3Fillcode%3Ds1br%26database%3Dliterati
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=referrer&referrer=http%3A%2F%2Flalibcon.state.lib.la.us%2Fredirect.php%3Fillcode%3Ds1br%26database%3Dliterati&institutionId=7172


Geo-location Institution Authentication

Client sends its credentials along with institution IP address to security API and get access + refresh token pair back. Client is authenticated as nearest institution to location of specified IP address.

URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=geo_ip&ip=$ip_address

HTTP Method
GET POST

Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=geo_ip&ip=168.20.193.33


Library Card Institution Authentication

Client sends its credentials along with institution ID and library card number to security API and get access + refresh token pair back. Institution ID is checked to be associated with specified library card number. In case of mismatch authentication is failed.

URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=libcard&libcard=$libcard&institutionId=$institutionId

HTTP Method
GET POST

Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=libcard&libcard=28040123456789&institutionId=1199


Shibboleth Institution Authentication

Besides getting institution object from Security API based on Shibboleth username, Security API also support following scenarios to obtain access token using Shibboleth authentication:

  1. Get access token based on shibboleth username
  2. Redirect user (institution) to shibboleth authentication page and get authorization code from API via redirect to client
  3. Redirect user (institution) to shibboleth authentication page and get authorization code from API as JSON response


Get Access Token Based on Shibboleth Username

Returns OAuth access token based on Shibboleth username provided as parameter value in the API call. This method is used when client authenticates institution within Shibboleth by itself. To support such method, client should accept redirects back from Shibboleth and hostname where client resides should be registered within Shibboleth.

URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=shibboleth&user=Member@testshib.org

HTTP Method
GET POST

Example
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=shibboleth&user=Member@testshib.org


Redirect User (Institution) to Shibboleth Authentication Page and Get Authorization Code from API via Redirect to Client

For this scenario there is NO requirement for the client to be registered within Shibboleth and accept redirects from Shibboleth. User (institution) will be redirected to Shibboleth authentication page, then it will be redirected by Shibboleth back to API with Shibboleth username as a parameter. Shibboleth daemon will check its validity and API will return authorization code through redirect to client.
Using of authorization code avoids passing client secret to Shibboleth in redirect and allowing Shibboleth to get access token by itself instead of redirecting back to API. Authorization code could be used only in pair with client secret to get access token.

URI Path
/v1/oauth/authorize?response_type=code&login_type=shibboleth&client_id=$client_id&redirect_uri=$client_entry_point_accepting_authorization_code&state=$state&entityId=$entityId

Entity ID is Shibboleth provider endpoint URL, which could be different depending on institution. After API gets correct username from Shibboleth it redirects back to client to following URL:

<redirect_uri>?code=<authorization_code>&state=<state>

State is optional parameter which is recommended to use and initiated from client to make sure redirect_uri is accessed by API which knows state from client and no one else. After client receives authorization code it should be exchanged to access_token. Redirect_uri parameter is added to token request for validation by oauth (it will check that request_uri matches authorization code it was generated for):

/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=authorization_code&code=$authorization_code&redirect_uri=$redirect_uri

HTTP Method
GET

Example
Get redirect with authorization code:

/v1/oauth/authorize?response_type=code&login_type=shibboleth&client_id=literati_server&redirect_uri=http%3A%2f%2fgoogle.com&state=5dj3kq

Exchange authorization code to access token:

/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=authorization_code&code=$authorization_code&redirect_uri=http%3A%2f%2fgoogle.com



Redirect User (Institution) to Shibboleth Authentication Page and Get Authorization Code from API as JSON response

For this scenario there is NO requirement for the client to be registered within Shibboleth and accept redirects from athens. User (institution) will be redirected to Shibboleth authentication page, then it will be redirected by athens back to API with Shibboleth username as a parameter. Shibboleth daemon will check its validity and API will return authorization code in JSON response.

URI Path
/v1/oauth/authorize?response_type=code_response&login_type=shibboleth&client_id=$client_id

After API gets correct Shibboleth username it sends back to client authorization code:

{"code":"asdf34"}

After that client should get access token by authorization code using URL:

/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=authorization_code&code=$authorization_code

HTTP Method
GET

Example
Request authorization code:

/v1/oauth/authorize?response_type=code_response&login_type=shibboleth&client_id=literati_server

Exchange authorization code to access token:

/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=authorization_code&code=$authorization_code



Application API

Get Application by Key

Checks if application key is specified correctly and returns application descriptor object. OAuth access_token should be passed as a parameter for accessing this API.

URI Path
/v1/application/auth/$app_id?key=$app_key&access_token=$access_token

HTTP Method
GET POST

Example
/v1/application/auth/literati_server?key=$key&access_token=<access_token>
JSON response will be in following format:

{
    "appId": "literati_server",
    "name": "Literati",
    "description": "Credo's web app for Information Literacy",
    "contactName": "Nancy King",
    "contactEmail": "nancy.king@credoreference.com",
    "company": "Credo Reference",
    "grantTypes": [],
    "authorities": [
        "ROLE_TRUSTED_CLIENT"
    ],
    "dateCreated": "2012-06-06T19:08:25Z",
    "lastUpdated": "2012-06-06T19:08:25Z",
    "active": true,
    "base": "http://alpha.api.credoreference.com"
}
        


Institution API


Authenticate Institution by Shibboleth

Resolves institution by shibboleth user. This is internal API to be used by trusted client. Trusted client should accept redirect from Shibboleth, get shibboleth user from redirect request parameters and pass shibboleth user to API to resolve institution. OAuth access_token should be passed as a parameter for accessing this API.

URI Path
/v1/institution/shibboleth?user=$shibboleth_user&access_token=<access_token>

HTTP Method
GET POST

Example
/v1/institution/shibboleth?user=test@bowdoin.edu&access_token=<oauth_access_token>

Interaction with other API services

API services are proxied by Security Facade. To call API service client should use /v1/ prefix and add access_token parameter to URL.

URI Path
/v1/$API_URL_WITH_PARAMETERS&access_token=$oauth_access_token

HTTP Method
GET POST

Example
/v1/search/dna?access_token=<oauth_access_token>