Registering Endpoints


An endpoint is short for “resource endpoint”. Basically, it represents some resource that is accessible via some URL. If the endpoint is written in a RESTful style, the resource will be accessible using standard HTTP verbs (GET, POST, DELETE, etc.).

Note that if you’re just using OAuth for user authentication, and don’t need to implement your own resource endpoints, then you can completely skip this part. Oauth.Us comes with several resources built-in that you can use without any further configuration.

Architecture


Most of the time, the resource server and OAuth providers are from the same organization (i.e., use Facebook’s OAuth provider to access Facebook profiles). Using Oauth.Us, however, we can implement our own resource API without being tied to any particular provider.

In Oauth.Us, providers can interface with existing API endpoints regardless of what framework those endpoints were written in (Node.js, Python, Java, etc.). So long as the resource server only accepts connections from the authorization server, users will be forced to authenticate before using the API.

User Resources


Oauth.Us comes with a few built-in resources that can be accessed by any authorized client application.

GET /user?user_id='alex@me.com'&access_token='abcd'
{
  'name' : 'Alex Button',
  'type' : 'admin',
  'phone' : '111-222-3333',
  'address1' : '1 Way',
  'address2' : 'State, Country',
  'user_id' : 'alex@me.com',
  'apps' : [{
              'client_id' : '12xxdd...',
              'name' : 'Admin App',
              'homepage' : 'myapp.com'
           }]
}

There are also methods to update and delete users.

PATCH /user?user_id='alex@me.com'&access_token='abcd'
DELETE /user?user_id='alex@me.com'&access_token='abcd'

Registering an Endpoint


To register an endpoint, you first need to access the administrative portal. First navigate to the main provider page, and click on Admin Portal. This should redirect you to the administrative portal for your provider. From the administrative portal, navigate to the “endpoints” page, and click “add endpoint”.

docs/../../../_static/img/new_endpoint.png

From there you’ll need to specify the URL, resource, and HTTP method. Afterwards, you’ll need to define which scopes the endpoint requires. You can enter any set of comma-delimited strings here. If the client application includes those scopes, it will be able to access the endpoint. Otherwise, it won’t be able to access the endpoint.

Accessing an Endpoint


After the endpoint is registered, client applications can access those resources using a modified URL. Say that the original resource was located at:

GET $RESOURCE_SERVER/myresource?param1='a'

After registering, you can access the same resource via:

GET https://192.168.56.110:8999/api/myresource?param1='a'&access_token='abcd'

Note that the client application has to go through the authorization server now and supply an access token.