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.
choosing-scopes.png 68.75 KB

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.



How did we do with this article?