# OAuth scopes

Scopes in OAuth 2.0 limit the amount of access granted to an access token. In OpenIAM, scopes are modeled as **resources** in the resource catalog and managed through the Resource Manager interface.

## Default scopes

OpenIAM ships with 21 default scopes. You can find them in **Access Control → Resources**, filtered by **Resource type = oAuth Scope**.

The default scopes are:

`address`, `birthdate`, `email`, `email_verified`, `family_name`, `gender`, `given_name`, `locale`, `middle_name`, `name`, `nickname`, `phone`, `phone_number_verified`, `phone_NUMERIC`, `picture`, `preferred_username`, `profile`, `updated_at`, `user_name`, `website`, `zoneinfo.`

<figure><img src="/files/FTk5SMrzPqcfSOSIIDdA" alt=""><figcaption></figcaption></figure>

## Viewing supported scopes for a Provider

To see which scopes your authentication provider supports, use the **OpenID Connect Discovery URL**:

1. Go to **Access Control → Authentication Providers**.
2. Open your OAuth provider (client).
3. Copy the value from the **OpenID Connect Discovery URL (Readonly)** field.
4. Open the URL in a browser — the `scopes_supported` array lists all available scopes.

<figure><img src="/files/TTOP91Bhq2o0qqrtTctm" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Imh1NmCgWySPeyokmHYC" alt="" width="380"><figcaption></figcaption></figure>

## Adding scopes to an Authentication Provider

1. Go to **Access Control → Authentication Providers**.
2. Find your OAuth provider and click **Edit**.
3. In the **Default Scopes** field, select the scopes you want to include.

<figure><img src="/files/0TamqzmtK5RLZ8QtgDsM" alt=""><figcaption></figcaption></figure>

4. Click **Save**.

## Custom scopes

OpenIAM allows creating custom scopes. For this you should create new resource with type oAuth Scope and provide link to a groovy script in a `Groovy Script` field. Enable **Is Public** checkbox. This is a mandatory condition for a scope resource. Script must extend the `AbstractOauthScopeResolver` class and override `getValue`method.

Output of the script will be sent as a value of the scope. Example of such scripts you can find in groovy manager in `/AM/oauth/` folder.

<figure><img src="/files/d6Utcwe41pccUEkYnJYG" alt=""><figcaption></figcaption></figure>

### Creating a Custom Scope

1. Go to **Access Control → Resources** and select **Create new resource** from the left menu.
2. Set **Resource type** to **OAuth scope**.

<figure><img src="/files/grXcvMZw1G1OI6jlro3F" alt="" width="563"><figcaption></figcaption></figure>

3. Enter a name, set status to **Active**, and enable the **Is Public** checkbox — this is mandatory.
4. In the **Groovy Script** field, provide the path to a Groovy script that extends `AbstractOauthScopeResolver` and overrides the `getValue` method.
5. Click **Save**.

The new scope will appear in the `scopes_supported` section of the discovery URL and can be added to any authentication provider.

<figure><img src="/files/OwQL8WjfwthGKgeYKhH1" alt=""><figcaption></figcaption></figure>

### Example: Return user roles

The script below returns the user's roles as a comma-separated string. It can be found in Groovy Manager at `/AM/oauth/RolesAbstractOauthScopeResolver.groovy`.

{% code overflow="wrap" expandable="true" %}

```groovy
import org.openiam.ui.security.oauth.groovy.AbstractOauthScopeResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import java.util.Set;
import org.openiam.am.srvc.dto.jdbc.RoleAuthorizationRight;
import org.openiam.srvc.am.AuthorizationManagerWebService;

public class RolesAbstractOauthScopeResolver extends AbstractOauthScopeResolver {

    @Autowired
    @Qualifier("authorizationManagerServiceClient")
    private AuthorizationManagerWebService authorizationManager;

    public RolesAbstractOauthScopeResolver() {
        super();
    }

    @Override
    public Object getValue() {
        final Set<RoleAuthorizationRight> set = authorizationManager.getRolesForUser(this.user.getId());
        final StringBuilder sb = new StringBuilder();
        if(set != null) {
            int idx = 0;
            for(final RoleAuthorizationRight right : set) {
                if(right != null && right.getEntity() != null) {
                    sb.append(right.getEntity().getName());
                    if(idx++ < set.size() - 1) {
                        sb.append(",");
                    }
                }
            }
        }
        return sb.toString();
    }
}
```

{% endcode %}

### Example: Return a user attribute value

The script below returns the value of a specific user attribute (`cif`). It can be found at `/AM/oauth/CIFAbstractOauthScopeResolver.groovy`.

{% code overflow="wrap" expandable="true" %}

```groovy
import org.openiam.ui.security.oauth.groovy.AbstractOauthScopeResolver;
import java.util.Set;
import org.openiam.idm.srvc.user.dto.UserAttribute;
import org.apache.commons.collections4.CollectionUtils;

public class CIFAbstractOauthScopeResolver extends AbstractOauthScopeResolver {

    public CIFAbstractOauthScopeResolver() {
        super();
    }

    @Override
    public Object getValue() {
        final UserAttribute attribute = this.user.getAttribute("cif");
        return (attribute != null && CollectionUtils.isNotEmpty(attribute.getValues())) ?
                (attribute.getValues().size() > 1 ? attribute.getValues().toString() : attribute.getFirstValue()) : "";
    }
}
```

{% endcode %}

All custom Groovy scripts for scopes must extend `AbstractOauthScopeResolver`. Additional examples are available in the Groovy Manager under `/AM/oauth/`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-beta.openiam.com/federation/oauth-scopes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.