Skip to content

Manage OIDC Scopes

In WSO2 Identity Server, each piece of user information is mapped to a user attribute.

OpenID Connect (OIDC) Scopes are a convenient way of grouping such user attributes. Applications can use scopes to request access to the user attributes corresponding to them. Access to other attributes that do not belong to the requested scopes is restricted.

Default OIDC scopes

WSO2 Identity Server uses openid as a marker scope during authentication and it will not return any user attributes for the openid scope.

Listed below are the default OpenID Connect scopes that applications can request and the corresponding user attributes:

Scope Description Attributes
profile This requests to retrieve profile information of the user.
  • name
  • family_name
  • given_name
  • middle_name
  • nickname
  • preferred_username
  • profile
  • picture
  • website
  • gender
  • birthdate
  • zoneinfo
  • locale
  • updated_at
email This requests access to the end-user's email related claims.
  • email
  • email_verified
address This scope value requests access to the address view of the user. This will return sub fields of the address claim.
  • address
  • street_address
phone This scope value requests access to the information related to the phone number of the user.
  • phone_number
  • phone_number_verified
groups This scope value requests access to the groups to which the user belongs.
  • groups

Create custom scopes

To add new scopes to your organization:

  1. In the WSO2 Identity Server Console, go to User Attributes & Stores > Attributes > Manage Attribute Mappings > OpenID Connect > Scopes.
  2. Click New OIDC Scope to open the Create OpenID Connect Scope dialog box.

    Create OpenID Connect scopes

  3. Enter values for the required properties and click Next:

    Scope The scope name that will be shared with applications.
    Display name The scope name that will be displayed in the Scopes section. Applications should use this scope name to request the corresponding attributes.
    Description The description of the scope.

  4. Select the attributes that should correspond to the scope and click Finish.

    Select attributes corresponding to scope

Edit Scopes

You can add attrbutes to scopes or delete them by following the steps below.

  1. On the WSO2 Identity Server Console, go to User Attributes & Stores > Attributes > Manage Attribute Mappings > OpenID Connect > Scopes.

  2. Select the scope to edit.

  3. To add a new attribute to the scope:

    1. Click New Attribute.
    2. Select the attribute you wish to add and click Save.
  4. To delete an attributes from a scope, click the trash icon next to it.

  5. Click Save Changes to save the updates.

Use scopes to request attributes

As an application developer, you can follow the steps given below to configure your applications to request user attributes using scopes.

  1. First, go to the WSO2 Identity Server Console and select user attributes for your application.

  2. Copy the scopes listed at the end of the User Attributes section.

    Selected Scopes

  3. When configuring the authentication request in your client app, append the scope parameter with the scopes that you need:

    • For client apps using the SDK:

      {
        "clientID": "<client ID>",
        "baseUrl": "https://localhost:9443",
        "signInRedirectURL": "https://localhost:3000",
        "signOutRedirectURL": "https://localhost:3000",
        "scope": [ "openid", "address", "phone", "profile" ]
      }
      

      Note

      Find out more about configuring applications.

    • For client apps using direct API calls to authenticate:

      curl -X GET \
      https://localhost:9443/oauth2/authorize \
        -d 'client_id={client_id}'
        -d 'response_type=code'
        -d 'redirect_uri={redirect_uri}'
        -d 'scope=openid%address%phone%profile'
      

When the user logs in, WSO2 Identity Server will prompt the user with a consent screen to authorize access to the user attributes. Once the user consents, your application will have access to the requested user attributes.