Scopes

Introduction

There are two different type of scopes: Identity Scopes and API Scopes

Identity Scopes

Identity Scopes are used to give applications access to a set of predefined claims. By bundling user claims such as firstname, lastname and username into a profile scope we can achieve multiple advantages. First of all we can control the access to those claims by only allowing the necessary scopes in the client configuration. Secondly we simplify the process for the application / client as it simply can request the whole scope instead of each claim individually. Lastly we give the user control over his own scopes by presenting him with a consent screen before accessing an application. On that screen he will see exactly which data an application / client is requesting and he has the option to confirm or deny the request.

API Scopes

API Scopes are used to give a clients (and not users) access to any given API resources. They represent a either an API as a whole or a function within such an API. How you structure those is entirely up to you. You could create an API Scope webshopadmin which gives the client full permission to an webshop API or you could further structure it down an create sperate API scopes for things like webshop.readproduct and webshop.placeorder.

If you assign a API scope to a client in the client configuration, you basically give that client access to the API resource. But make sure to actually check the presence of that scope in the implementation of your API!

Parameter

If you create an identity or api scopes, the following information is needed.

Name	Datatype	Mandatory	Example	Description

Name	Datatype	Example	Description
Name	String	delivery_address	The name of the scope as it will be stored in the id token or delivered by the user info endpoint.
Description	String	All information in relation to your delivery address such as the city and postal code.	Used to display on the consent screen
Description name key	String	Customer.BestRun.Scope.DeliveryAddress	Key to translate the key into multiple languages
Display name	String	Delivery Address	The readable name of the name
Display name key	String	Customer.BestRun.Scope.DeliveryAddressDisplayName	Key to translate the key into multiple languages
Emphasize	Checkbox	true	Whether or not this scope should be emphasized on the content screen. If set, it will be displayed in a way that the user sees the importance of it.
Enabled	Checkbox	true	Whether or not this scope is enabled in the system
Required	Checkbox	true	Whether or not the user must give consent to this scope. If he does not give consent, the user is not able to use the application.
Show on consent screen	Checkbox	true	Whether or not this scope needs to be displayed on the consent screen. You can disable technical scopes here if you want.
Order	Integer	1	The order on the consent screen
Scope type	Drop Down	identity scope	The type of the scope `identity scope` or `api scope`
Show in discovery document	Checkbox	false	Whether or not the scope should be included in the discovery document

Claim Types

Each scope contains 0…n claim types associated to it. If an application requests the scope and the user gives consent, all claim types will be published in the id token or over the user info endpoint.

API Resources

Each scope contains 0…n API resources. If the scope is added to the client configuration, this gives the client access (and not the user) to said API resource.