Skip to content

Specs: Provider's configuration

Jump to bottom Edit New page
oleksandrkits edited this page Mar 7, 2019 · 13 revisions

To add a provider on oauthd, you just have to add two files:

  • /providers/{provider}/logo.png: 32x32px PNG logo
  • /providers/{provider}/conf.json: JSON file that contains all information about the endpoints.

To test the validity of your description, you can run npm test to see errors and warnings.

{
    "name": {Name}
    "url": {URL},
    "oauth1": {OAuth1 Object},
    "oauth2": {OAuth2 Object},
    "parameters": {Parameters Object},
    "href": {Href Object}
}

All fields are described below. You should keep them as compact as possible, they will be expanded using the default values and sugar

Name

The name of the OAuth provider. it is used for display purpose

e.g. name: "Facebook"

Url

Base URL of your OAuth provider. All relative path requests will use this base, and the API requests will use this scheme and host.

e.g. "url": "https://graph.facebook.com/"

OAuth1 Object

"oauth1": {
    "request_token": {Request Object}
    "authorize": {Request Object}
    "access_token": {Request Object}
    "request": {Request Object}
    "parameters": {Parameters Object}
}

OAuth2 Object

"oauth2": {
    "authorize": {Request Object}
    "access_token": {Request Object}
    "request": {Request Object}
    "parameters": {Parameters Object}
}

Request Object

To authorize your users, we need to have informations about your OAuth API. So for the request_token, authorize and access_token step, you have to define a {Request Object}.

If the request object contains only an url field, you can compact it to the url string itself.

a Request Object contains:

  • url: relative or absolute url of the endpoint. For the request field and if present, this must be an absolute url and only the scheme and domain are used (else this will use the url from the root scope).

e.g. "url": "/request_token"

  • format: the format of the provider's response in the callback. This set the "Accept" header in the request and forces the response parsing. It can be url, json, or an equivalent mime type.

e.g. "format": "json"

  • method: the method determines if the request_token / access_token / refresh or revoke request have to be done using post (default value) or get. In the revoke field, this can also be delete

e.g. "method": "post"

  • query: The query contains the parameters for the request. It’s an object with arbitrary keys and values.

e.g. 

"query": {
"client_id": "{client_id}",
"scope": "{scope}",
"redirect_uri": "{{callback}}"
}

  • headers: An object containing the http headers for the request. It's an object with arbitrary keys and values. This is not available in authorize fields.

  • extra: For authorize / access_token, this is an array of field name to pass in the final callback of the authorization process. This also permit to pass a value from authorize to access_token as a keyword (double braces, see below)

  • cors: Only for the request field, if set to true this will let the browser to do the API call instead of proxyfying by oauthd.

  • ignore_verifier: Only for oauth1.authorize, this tell to ignore oauth_verifier and set the defaults for an OAuth 1.0 authorization (first version)

In a Request Object, you can use parameters and keywords to customize your call

Parameters are described in a {Parameters Object} section. They are into simple braces and let your user define their API keys/scope etc…

Keywords are used to allow you to perform all your request:

  • {{callback}} => replaced by the callback URL

  • {{state}} => replaced by the state of your app. If not present in the query, it will be included in {{callback}}

  • {{code}} => for oauth2.authorize, the received code

  • {{token}} => in oauth2.request and oauth2.refresh, replaced by the access token

  • {{refresh_token}} => in oauth2.refresh, replaced by the refresh token

  • {{nonce}} => replaced by a random string

  • {{code_verifier}} => replaced by a random 50 symbols length string for PKCE challenge.

  • {{code_challenge}} => replaced by a base64 URL-encode sha256 hash from {{code_verifier}}.

Example of a valid Request Object used for the Authorize step:

"authorize": {
      "url": "/authorize",
      "query": {
        "scope": "{scope}",
        "redirect_uri": "{{callback}}",
        "client_id": "{client_id}"
      }
}

Parameters Object

This object contains every configurable parameter from the Key manager and can be used in a Request Object when used into braces (e.g. "{client_id}").

If no parameters are present in the configuration, it will create a default client_id and client_secret pair.

You often have to add a scope which can take many values from a set.

e.g. 

"parameters": {
"client_id": "string"
"scope": {
"values": {
"choice1": "choice1 allow your user to do x",
"choice2": "choice2 allow your user to do y"
},
"separator": ","
}
}

If your parameter is a simple string, just set “string” as value

If your parameter is a list of item user have to choose (object values), you can set an object with a cardinality (“1” or “”) to know if the user can take one or many item (defaults to “”, say multiple) and a separator to be correctly passed in the request (defaults to " ", a space).

Parameters can be passed in the query using the following syntax:

"query": {
 	"client_id": "{client_id}",
  	"scope": "{scope}"
}

here, if the format is url, and if the user has set client_id to “qwerty” and scope to [“choice1”, “choice2”], the query string will be client_id=qwerty&scope=choice1,choice2

Here is the example of parameters used for the Facebook configuration file:

{
   "client_id": "string",
   "client_secret": "string",
   "scope": {
       "separator":",", // Separator for multiples values
       "values": { // Possible values and descriptions
          "read_friendlists":"Provides access to any friend lists the user created. All user's friends are provided as part of basic data, this extended permission grants access to the lists of friends a user has created, and should only be requested if your application utilizes lists of friends.",
          "read_insights":"Provides read access to the Insights data for pages, applications, and domains the user owns.",
          ...
       }
   } 
]

Href Object

the href object contains a list of url for help the developers to discover fastly helpful links:

  • keys is the url to get all the API keys (secret key / public key)

  • docs is the url to view the doc of your API

  • apps is the url to create and manage the user’s apps.

  • provider is the url of your site, with the sign up and login button.

e.g. for Github:

"href": {
    "keys": "https://github.com/settings/applications/new",
    "docs": "http://developer.github.com/v3/",
    "apps": "https://github.com/settings/applications",
    "provider": "https://github.com/"
}
Add a custom footer

Navigation

Clone this wiki locally