Skip to main content

​
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

​
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.