Letting resource owners choose scopes to be authorized

Overview

Authlete enables developers to build an authorization page where end-users (or resource owners) can choose scopes. This article describes how to use Authlete APIs to do that.

Obtaining a list of scopes from an authorization request

First you will need to know which scopes are requested by a client. They are included in an authorization request from the client with a parameter “scope.” Authlete’s /auth/authorization API parses the request and tells your authorization server the requested scopes, as an array of “scopes”. The following is an example request/response.

• Request

$ curl -s -X POST https://api.authlete.com/api/auth/authorization \
 -u ...:... \
 -H 'Content-type: application/json' \
 -d '{"parameters":
  "redirect_uri=...
   &client_id=...
   &response_type=code
   &scope=read+write"}'

• Response

{
  "type": "authorizationResponse",
  "resultCode": "A004001",
  "resultMessage":
   "[A004001] Authlete has successfully issued a ticket
    to the service (API Key = ...) for the authorization
    request from the client (ID = ...).
    [response_type=code, openid=false]",
...
  "scopes": [
    {
      "defaultEntry": false, "description": "Read",
      "descriptions": [
        { "tag": "en", "value": "Read" },
        { "tag": "ja", "value": "参照" } ],
    "name": "read"
    },
    {
      "defaultEntry": false, "description": "Write",
      "descriptions": [
        { "tag": "en", "value": "Write" },
        { "tag": "ja", "value": "更新" } ],
    "name": "write"
    }
  ]
...

With the values in “scopes”, you can craft an authorization page that allows end users to choose what kind of access can be granted to the requesting client.

Specifying the end user’s chosen scopes

Once the authorization server recognizes the end user’s intent, it will ask Authlete to issue an access token (and/or an authorization code) with the scopes that are chosen by the user.

Authlete’s /auth/authorization/issue API accepts a request including “scopes” that enables narrowing down scopes, which are initially requested in the authorization request from the client. By giving a non-empty string array as the value of the scopes parameter, Authlete replaces the scopes with it. The following is an example request/response for processing implicit grant flow.

• Request

curl -s -X POST https://api.authlete.com/api/auth/authorization/issue \
-u ...:... \
-H 'Content-type: application/json' \
 -d '{"subject":"...",
   "ticket": "...",
   "scopes":["read"]}
'

• Response

{
  "type": "authorizationIssueResponse",
  "resultCode": "A040001",
  "resultMessage":
    "[A040001] The authorization request was processed successfully.",
  "accessToken": "...",
  "accessTokenDuration": ...,
  "accessTokenExpiresAt": ...,
  "action": "LOCATION",
  "responseContent":
    "https://client.example.org/cb/example.com
     #access_token=...
      &token_type=Bearer
      &expires_in=...
      &scope=read"
}

As a result, the authorization server will give the client the access token with the narrowed scopes.

Note that this function only narrows down the scopes originally requested at /auth/authorization API. The scopes parameter cannot include additional scopes that you did not request at the /auth/authorization API.