Using OpenID Scopes

OpenID scopes allow you to control the data that is returned to your application when using OpenID endpoints.

They are defined in the following section of the OpenID standard https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.

As a best practice, it is recommended limiting the accessible scopes to only those needed by the client application using the scope parameter. When the scope parameter is empty or not present, the client application can access all scopes.

The OpenID endpoints that are affected by the configuration of scopes are Token (ID Tokens) and UserInfo.

The configuration of a scope is attached to the Client ID, and can be changed using the OpenID Register endpoint. For details about updating the client configuration, see Managing Users, Groups and Roles.

The following is an example of a response from the Register endpoint (with details of the configuration of a Client ID): 

Copy 
{
   "hid_sessiontransfer_type": "NUM001",
   "grant_types":    [
      "client_credentials",
      "password",
      "authorization_code"
   ],
   "hid_refresh_token_validity": "3600",
   "registration_client_uri": "https://[base-server-url]/{tenant}/authn/register/217814155446168647154048505874144336229481841822",
   "redirect_uris":    [
      "https://client2.example.org",
      "https://client.example.org"
   ],
   "hid_client_channel": "CH_EXTRAPP",
   "token_endpoint_auth_method": "client_secret_basic",
   "client_id": "217814155446168647154048505874144336229481841822",
   "hid_client_pwd_policy": "AT_SYSLOG",
   "hid_client_consentprompt": "false",
   "hid_client_pki_policy": "AT_SYSPKI",
   "hid_client_scopes": "{\"scopes\":[\"openid\",\"profile\",\"offline_access\"]}",
   "hid_user_channel": "CH_EXTRAPP",
   "hid_user_authn_policy": "AT_STDPWD",
   "client_id_issued_at": 1579173681,
   "tls_client_certificate_bound_access_tokens": false,
   "client_name": "test-rt"
}

The parameter of the register endpoint that allows you to configure scopes is hid_client_scopes:

Copy 
"hid_client_scopes": "{\"scopes\":[\"openid\",\"profile\",\"offline_access\"]}"

The value of this parameter is a character string containing escaped JSON formatted data; this defines an array of authorized scopes. Here we can see that the scopes openid, profile and offline_access are defined. These scopes are the default scopes that the HID Authentication service implicitly defines:

  • openid is the default scope for any OpenID endpoint

  • profile is to be used to fetch data about the user's profile (basically used to get an ID Token along with an access token)

  • offline_access is used to enable refresh tokens

You can either redefine the default scopes or create new ones by using the JSON syntax below (do not forget to escape the JSON when passing it in the parameter hid_client_scopes: 

Copy 
{
  "scopes": [
    {
      "scope1": {
        "claims": {
          "userinfo": {
            "usr.ATR_EMAIL": {
              "essential": true
            },
            "usr.ATR_MOBILE": {
              "essential": false
            },
            "usr.CITY": {
              "essential": false
            }
          },
          "id_token": {
            "usr.groupids": {
              "essential": true
            },
            "usr.roles": {
              "essential": false
            }
          }
        }
      }
    },
    {
      "openid": {
        "userinfo": {
          "usr.ATR_EMAIL": {
            "essential": true
          },
          "usr.ATR_MOBILE": {
            "essential": false
          }
        },
        "id_token": {
          "usr.groupids": {
            "essential": true
          },
          "usr.roles": {
            "essential": false
          },
          "acr": {
            "essential": true
          }
        }
      }
    },
    "profile"
  ]
}

The userinfo and id_token JSON structures respectively define the attributes in the authn/userinfo and authn/token endpoints. The attributes are defined with the usr. prefix followed by the name of the user attribute, for example usr.ATR_EMAIL for the user's email address. The HID Authentication Service defines three special attributes:

  • usr.groupids for the user group

  • usr.roles for the roles of the user.

  • acr for the Authentication Policy used for the authentication.

The request to update the Client ID with new scopes:

Copy 
PUT https://[base-server-url]/{tenant}/authn/register HTTP/1.1
Content-Type: application/json
{
    "client_id": "217814155446168647154048505874144336229481841822",
    "hid_client_scopes": "{\"scopes\":[{\"scope1\":{\"claims\":{\"userinfo\":{\"usr.ATR_EMAIL\":{\"essential\":true},
                         \"usr.ATR_MOBILE\":{\"essential\":false},\"usr.CITY\":{\"essential\":false}},\"id_token\":{\"usr.groupids\":
                         {\"essential\":true},\"usr.roles\":{\"essential\":false}}}}},{\"openid\":{\"userinfo\":{\"usr.ATR_EMAIL\":{\"essential\":true},
                         \"usr.ATR_MOBILE\":{\"essential\":false}},\"id_token\":{\"usr.groupids\":{\"essential\":true},\"usr.roles\":{\"essential\":false},
                         \"acr\":{\"essential\":true}}}},\"profile\"]}"
}

Once the Client ID is updated, we can pass the scope parameter when requesting a token or userinfo and see that we obtain more details about the user:

Copy 
POST https://[base-server-url]/{tenant}/authn/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
            
grant_type=password&username=YOUR_USERNAME&password=YOUR_USER_PASSWORD&scope=openid profile

The response contains an ID Token that shows the groups and roles of the user (see Making the Most of OpenID Tokens):

Copy 
{
    "kid": "1578064077008",
    "typ": "JWT",
    "alg": "RS256"
}
            
{
    "at_hash": "eoPNhKIN2fJTnhYYN4fPLA",
    "sub": "test@mail.fr",
    "aud": "217814155446168647154048505874144336229481841822",
    "acr": "urn:hidaaas:policy:at_stdpwd",
    "auth_time": 1579182833,
    "groupids": [
        "UG_ORGADMIN"
    ],
    "roles": [
        "RL_ORGADMIN"
    ],
    "iss": "https://[base-server-url]/{tenant}/authn",
    "preferred_username": "test@mail.fr",
    "exp": 1579186433,
    "iat": 1579182833
}