Defining Scopes for a Resource Server

A scope is a set of permissible actions that a client application can perform on the accessed resources. You can define scopes by providing user claims, such as user attributes and permissions. The client application developer can request for required scopes, which an administrator uses for configuring the resource server in Identity Server (authorization server). However, there is no restriction for any client application to use any of the scopes configured in any resource server. For more information, see Adding a Resource Server. It is recommended to select Require user permission to get consent from the user whenever the scope contains user attributes.

When a user grants client applications access to protected resources, they can perform actions based on permissions defined in the scope.

For example, if you have defined a scope named email and defined permissions associated with this scope, such as read only. A client application that will access the email can only read the content.

NOTE:

  • You can get LDAP-based attributes in a scope.

  • You can configure roles as an OAuth scope and use them to inject with the Identity Injection policy. The role attribute is calculated when a token is sent to UserInfo Endpoint.

  • If you have registered a client application to use binary token, you cannot add user attributes and claims to the token.

Perform the following steps to define scopes and permissions:

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Server.

  2. Select the resource server name for which you want to define a new scope.

  3. Click New and specify the following details:

    Field

    Description

    Name

    Specify a name for the scope.

    Description

    Specify a description for the scope. The consent page shows this description.

    Include claims of type

    Select the type of user’s claim to be used in the scope. You can select any of the following types:

    • User Attributes: Select this option if you require using any of the user’s LDAP attributes in the scope. You can also use virtual attributes in the scope.

      NOTE:

      • You can use virtual attributes for LDAP-based attributes and constant values.

      • This option does not work in a client credentials flow.

    • Custom Claims/Permissions: Select this option if you want to restrict specific permissions for this scope. This option is useful when a client application requires specific permission, such as read, write and so on to access a resource.

      For example, when you configure a read permission for the scope, the client application can request for this scope and get the token.

    Require user permission

    Select this option if this scope requires user’s consent before providing access to the protected resources. It is recommended to keep this option selected when user attribute is used in the scope.

    In a client credentials flow, the token does not include scopes that require user permissions. Therefore, deselect this option. When the option is deselected, the claims can be fetched from the UserInfo Endpoint.

    • When this option is enabled and the prompt=consent parameter is sent in the authorization endpoint, the user consent screen is displayed.

    • When this option is enabled, and the prompt=none parameter is passed in the authorization endpoint, the user consent screen is not displayed.

    • When this option is disabled, and the prompt=none parameter is passed in the authorization endpoint, the user consent screen is not displayed.

    • When this option is disabled, and the prompt=consent parameter is passed in the authorization endpoint, the user consent screen is not displayed.

    NOTE:If you deselect this option, the scope is not listed in the scopes_supported field of the metadata endpoint. The claims_supported field of the metadata endpoint does not display the claims for this scope even if the user attribute or the custom claims/permissions are configured.

    Allow modification in consent

    Select this option to allow modification in consent. When selected, the resource owner can choose not to share the scope with the client application.

    The consent page will display a check box against each scope to choose the scopes that can be shared with the client applications.

  4. Click Next and continue with Configuring User Claims or Permission in Scope.

Configuring User Claims or Permission in Scope

You can include user’s attributes or a client application’s claim in the scope.

  1. (Conditional) If you chose User attributes to create scope, perform the following steps:

    1. Select the required attribute set from the LDAP profile or create a new attribute set.

      This lists the user attributes in the attribute set.

      NOTE:You can add any configured LDAP based virtual attribute to the scope of the access token. You can add a virtual attribute by creating an attribute set that includes the virtual attributes. For information about creating an attribute set, see Configuring Attribute Sets.

    2. To add the user attribute scope to the access token, select the required attributes that should be added to the access token, then click Add > Add to Access Token.

      If you want to remove a specific attribute from the access token, click Remove > Remove from Access Token. When you remove the attribute from the access token, the attributes will not be removed from the already issued token.

    3. To add the user attribute scope to the ID token, select the required attributes that should be added to the ID token, then select Add > Add to ID Token.

      NOTE:The token size varies based on the attribute value that is included in the token. Hence, it is recommended to include only the required attribute to the token.

      If you require to remove a specific attribute from the ID token, select the attribute then click Remove > Remove from ID Token.

      NOTE:The attributes are not added to or removed from an issued ID token.

    4. (Conditional) If you require the selected attributes to be available in both ID token and access token, then after selecting the attributes click Add > Add to Both.

      If you require to remove specific attributes from both access token and ID token, then after selecting those attributes click Remove > Remove from Both.

  2. (Conditional) If you have used Custom Claims/Permissions, perform the following:

    1. Click New to create a new custom claim.

    2. In Add claim/permission, specify the permission that the client is allowed after consuming the access token.

    3. Select the required claim that to be added to the access token, then select Add > Add to Access Token.

      To remove a specific claim from an access token, click Remove > Remove from Access Token.

      NOTE:The claims are not added to or removed from an already issued access token. You can view the new Claims/Permissions in the claims set. The key name is claims and the value is a list of strings.

    4. Select the required claim to be added to the ID token, then select Add > Add to ID Token.

      To remove a specific claim from the ID token, click Remove > Remove from ID Token.

      NOTE:Claims are not added to or removed from an issued ID token. You can view the new Claims/Permissions in the claims set. The key name is claims and the value is a list of strings.

    5. (Conditional) If you require to select the claims that must be available for both access token and ID token, then after selecting the claims click Add > Add to Both.

      To remove claims from both tokens, select claims, and click Remove > Remove from Both.

      NOTE:The claims are not added to or removed from the already issued tokens. These claims are displayed as list of strings under the claims attribute in access and ID tokens.

Managing Scopes of a Resource Server

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Server.

  2. Click the resource server > scope you want to modify.

  3. On the Edit Scope page, modify the details as required. For information, see Defining Scopes for a Resource Server.

  4. Click OK.

Modifying Claims and Attributes

You can modify or delete a defined claim. You can also update the attributes associated with a scope. If you have selected Require user permission while creating the scope, Identity Server fetches the required information from the userinfo endpoint. You can change the associated LDAP attributes.

To delete a custom claim or permission, you can select the required permission and click Delete.

For information about user attributes and claims, see Defining Scopes for a Resource Server.