Scope registration

About scopes

As defined in this Scope section scopes are identifiers for resources that a client wants to access. The Unit4 Identity Services (U4IDS) supports two types of scopes, identity scopes and resource scopes. By default U4IDS is configured with the OpenID standard scopes:

• openid - (identity scope) this scope informs U4IDS that the client is making an OpenID Connect request. If this scope value is not present, the authentication behavior is entirely unspecified.
• profile - (identity scope) this scope enabled clients to request profile claims form the UserInfo endpoint.
• email - (identity scope) this scope enabled clients to request email claims form the UserInfo endpoint.
• address - (identity scope) this scope enabled clients to request address claims form the UserInfo endpoint.
• phone - (identity scope) this scope enabled clients to request phone claims form the UserInfo endpoint.
• offline_access - (resource scope) this scope enabled clients to request offline access, this scope dictates that U4IDS will return a refresh token from the token endpoint. This scope is relevant for applications that implement the hybrid authentication flow.

See scope values for information about the standard scopes.

Resource scopes

Resource scopes are used to define and identify web APIs (resource servers). When you want to implement an authentication scenario for an application it is important to identify the resources that the application (client) requires access to. If the application requires access to a single resource server, this Web API can be registered as a resource scope with U4IDS.

When the scope is configured and registered with U4IDS, the client requesting access to the resource need to pass the scope name in the authentication request made to U4IDS (authority). The resource server needs to implement token validation that involves making sure that the scope is present in the token.

Note

The scope name must be unique and you must apply a proper description so that the intention of the scope is clear. As U4IDS will be used as a federation gateway for several products, it is important that you define and enforce rules when it comes to how scopes are defined and named.

Scope secrets

You can configure a scope with a set of scope secrets. You then model the scope as a client. If this configuration is applied, the scope name and secret must be registered (in a secure place) and used by the client on the resource server and be used to validate the token. You must then use introspection rather than standard token validation of the token.

Allow scopes

By default a client has no scopes configured with U4IDS. You need to decide if the client should have access to all scopes or a restricted list of scopes. If the client should have access to all scopes, then set the AllowAccessToAllScopes to true.

The recommended approach is to use the AllowedScopes property to explicitly define the scopes that the client has access to.

Scope claims

You have the ability to attach user claims to your scopes, scope claims are configured via the Claims property of the scope. How scope claims are treated by U4IDS depends on the scope type. If the scope is of type Resource the claims will be included in the access token. An applicable scenario might be if you want to include the users role in the access token so that resource servers can implement authorization.

{
    "Name": "roles",
    "Type": "resource",
    "Claims": [
        { "name": "role" }
    ]
}

For identity scopes you have more flexibility. The standard usage is to configure a scope with a set of claims, the claim values will be obtained via the UserInfo endpoint. You have the option to specify that the user claims should be included in the id token.

Using Scopes makes it possible to define partitions (subsets) of the API. These partitions can be used on the consent screen to inform the user which elements of the API the clients want to use. For more details on scopes configuration on the Unit4 Identity Services (U4IDS), see Scope configuration.

How to register a scope?

There are two available methods for registering scopes, see Administrator toolkit overview. For more details about scope properties and scope localization see scope configuration.

Scope registration examples

Identity scope with claims

Example

{
    "Name": "roles",
    "Description": "Roles for a user",
    "Type": 0,
    "Claims": [
        {
            "Name": "role"
        }
    ]
}

Identity scope with claims, always include

Example

{
    "Name": "roles",
    "Description": "Roles for a user",
    "Type": 0,
    "Claims": [
        {
            "Name": "role",
            "AlwaysInclude": "true"
        }
    ]
}

Simple resource scope for resource server

Example

{
    "Name": "webapi",
    "Type": 1
}

Resource scope with claims

Example

{
    "Name": "roles",
    "Description": "Roles for a user added to access token",
    "Type": 1,
    "Claims": [
        {
            "Name": "role"
        }
    ]
}

Resource scope with secret

Example

 {
    "Enabled": "true",
    "Name": "webapiwithsecret",
    "type": 1,
    "ScopeSecrets": [
        {
        }
    ]
  }

Secret will be returned in response from Admin API.