API Resource

Introduction

What is an API resource?​

API resources, a.k.a. Resource Indicators, indicate the target services or resources to be requested, usually, a URI format variable representing the resource's identity.

Why is API resource needed?​

Auth, as an authorization server, is designed to serve a large number of services and APIs. By indicating which API resource an end-user intends to access, Auth can issue a private encrypted authorization token and apply audience restrictions accordingly.

A guarded request with an authorization token provided will help you protect your private resources from being accessed and attacked by anonymous identities.

Definitions

Resource Indicator​

● A resource value indicates the target service or resource to which access is being requested.

● Its value MUST be an absolute URI.

● The URI MUST NOT include a fragment component.

● It SHOULD NOT include a query component.

● You SHOULD provide the most specific URI it can for the complete API or set of resources it intends to access.

In practice, a client may know a base URI or the application or resource to interact with. It would be appropriate to use it as the value of the resource parameter.

E.g., Auth management API base URI.

https://your-accounts-api.yourdomain.com/

By default, this API resource is pre-registered to your Auth service. All the management APIs under this URI are protected by Auth.

Auth API Resource Schema​

Property Name	Property Description	Required
API Name	A user friendly name that can help you to identify the API resource.	true
API Identifier	The unique API Resource Indicator value, with restrictions listed above. Auth will use it to identify the requested API resource and grant the authorization tokens accordingly.	true
Token expiration time (in seconds)	The expiration time set for access_token. The default expiration value is 3600.	false

CAUTION

Requests with a expired access_token should be restricted. This is implemented to protect your API from a abused token. The larger value is set, the longer will a issued access_token survive, and the more vulnerable your API will be.

How does it work​

1. Authorization request​

Provide a list of resource indicator parameters in an authorization request. It will indicate all the protected resource(s) that the user may request.

GET https://nightly-accounts-api.complyment.com/authz?response_type=code
    &client_id=s6BhdRkqt3
    &state=tNwzQ87pC6llebpmac_IDeeq-mCR2wLDYljHUZUAWuI
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    &resource=https%3A%2F%2Fauth.dev%2Fapi%2Fapplications
    &resource=https%3A%2F%2Fauth.dev%2Fapi%2Fusers

Auth will validate and store these resource indicators. An authorization_code will be granted and returned with scopes restricted to these specified resources.

2. Access Token request​

When the resource parameter is present on an access token request along with the authorization_code granted above, it will specify the target API resource audience of the access token is requested.

POST https://nightly-accounts-api.complyment.com/token HTTP/1.1
    grant_type=authorization_code
    redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
    code=10esc29BWC2qZB0acc9v8zAv9ltc2pko105tQauZ
    resource=https%3A%2F%2Fauth.test.dev%2Fusers

An encrypted access token with the audience restricted to this requested resource will be granted by Auth. The token carries all the data you will need to represent the authorization status of the request. E.g., the request user's identity and role, the token's audience and expiration time.

3. API resource request​

The client user sent a request to the API resource by presenting the given access_token in the Authorization header.

GET https://nightly-accounts-api.complyment.com/users-info
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzd

TIP

Please follow our Protect Your API guide to implement the token validation on your server-side APIs and make your resources well protected.

Auth follows the standard token-based authorization protocol to protect your API resources. To learn more about OAuth 2.0, please refer to OAuth 2.0's official document.