Configuring Custom Scopes for a Client

You can enable OpenID clients to request custom scopes, and configure the access to user attributes in ID Tokens and through the userInfo endpoint in the scopes.

Using the ActivID Management Console

1. Log on to the ActivID Management Console as an ActivID Administrator (for example, ftadmin).

2. To define the scope of the consent, select the Configuration tab and, under Environment, select Adapters.

3. Create an OpenID adapter or edit an existing one (for example, OpenID_admin) where:

   • Name – mandatory and should be unique for ease of administration.

   • Description – a user-friendly description of the adapter (optional).

   • Adapter Type – select Process to send notifications of operational events (such as user validations).

   • Adapter Category – select OpenID client (organization) configuration as the definition of the adapter.



4. Configure the main parameters (channels, authentication policies, …) as described in Create the OpenID Administrator for Dynamic Registration.

5. In the Client scopes field, define the consent scope in JSON format.

   In addition to the claims returned by the "claims_supported" metadata published by the OpenID provider (see Discovering the Server’s Endpoints and Capabilities), the following additional claims are supported:

   "usr.<attribute code>"

   "usr.groupids"

   "usr.roles"

   "usr.securitygroupids" (for security groups in SCIM federated repositories)

   For example:

   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",        
           "profile"
       ] }

   Note:

   • All entries prefixed by usr. are considered to be the names of user attributes, and the value is extracted from user's corresponding attribute.

   • “groupids” and “roles” are supported HID custom claims, and can be used to return user groups and roles. They need to be prefixed with “usr.” in the scope definition.

   • The "return" character is not supported by the adapter's parameter value. Any "return" characters should be removed from the JSON format.

   • ActivID AS only supports the “openid” and “profile” OpenID scopes. The other OpenID defined scopes (such as “email”, “address” etc) need an explicit definition in the client scopes field.

   If you leave the consent scope empty, the OpenID standard scope will be applied. It is equivalent to the following definition:

   Copy

   {"scopes":
           ["openid", "profile"]
   }

   The "openid" and "profile" scopes can be also overwritten by redefining the claims in these scopes, as follows:

   Copy

   {"scopes":[
          "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"]
       }

   Using the Client Dynamic Registration/Configuration API Endpoint

   An optional parameter, hid_client_scopes, is provided to dynamically register an OpenID client with the customized scope definition.

   Copy

   POST https://[base-server-url]/{tenant}/authn/register HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer RTp7HwAAAV6kDLkStyOElco4/XqhuFOnqCHTypGu
    
   {
   "redirect_uris": ["https://client.example.org/callback", "https://client.example.org/callback2"],
    "client_name": "OpenID Client 1",
    "token_endpoint_auth_method": "client_secret_basic",
   ……
    "hid_client_scopes": "{\"scopes\":[\"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\"]}",

   This request corresponds to the value of the following consent scope configured in the OpenID adapter configuration:

   Copy

   {"scopes":["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"]}