Manage OIDC Scopes

In Asgardeo, each piece of user information is mapped to a user attribute.

OpenID Connect (OIDC) Scopes (opens new window) 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

Asgardeo 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 Asgardeo Console, go to User Attributes & Stores > Attributes > Manage Attribute Mappings > OpenID Connect.
2. Under Manage Attribute Mappings, click OpenID Connect.
3. Click Scopes
4. Click New OIDC Scope to open the Create OpenID Connect Scope dialog box.
5. 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.

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

Edit Scopes

You can add or delete attributes to scopes based on your requirement.

1. On the Asgardeo Console, go to User Attributes & Stores > Attributes.
2. Under Manage Attribute Mappings, click OpenID Connect.
3. Click Scopes.
4. Click on a scope to edit.
5. To add a new attribute to the scope:
   1. Click New Attribute.
   2. Select the attribute you wish to add and click Save.
6. To delete an attributes from the scope, click the trash icon next to it.
7. 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 Asgardeo Console and see that your application has the required attributes enabled.

2. Copy the scopes listed at the end of the User Attributes section. You may have default OIDC scopes or custom scopes listed.

   

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://api.asgardeo.io/t/<organization_name>",
       "signInRedirectURL": "https://localhost:3000",
       "signOutRedirectURL": "https://localhost:3000",
       "scope": [ "openid", "address", "phone", "profile" ]
     }
     

     Find out more about configuring applications.

   • For client apps using direct API calls to authenticate:

     curl -X GET \
     https://api.asgardeo.io/t/<organization_name>/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, Asgardeo 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.