Where is scope (email) configured for access_token?

General
, , , ,
1

We have a frontend build outside Pega. When the frontend connects to Pega we are using oauth2 and tokens. When we look at the json-message containing the access_token (retrieved via the rest-API “token” in service package “oauth2”) we noticed that “email” is part of the scope eventhough (as far as we know) we didn’t specify any scope.

{
“sub”: “SNS2551838”,
“app_version”: “25.34”,
“iss”: “urn:www-t1.snsbank.nl”,
“psync_id”: “256f7e4d84eff68ebeb3704f164084c3”,
“operator_access”: “PcHypotheekC11n:Customer”,
“aud”: “urn:22709575095215276110”,
“app_name”: “PcHypotheekC11n”,
“nbf”: 1753971318,
“scope”: [
“app.alias.PcHypotheekC11n”,
“email”
],
“exp”: 1753973318,
“iat”: 1753972418,
“jti”: “72d484ce74fbf23db248122d99da797a”
}

We would like to know where this can be configured or is this something that is added by the Pega Platform?

I hope anybody can help us.
Kind regards,
René van Seuren

2

@Renév545

:warning: Below is an answer from a GenAI-powered tool and not verified.

All generated answers require validation against the provided references.

The scope for an access token is typically defined in the authentication service configuration within Pega. Here’s how you can check and configure it:

  1. Access the Authentication Service Configuration:

    • Navigate to the ‘Records’ explorer in Pega.
    • Go to ‘SysAdmin’ and then ‘Authentication Service’.
    • Open the specific authentication service you are using (e.g., OIDC, SAML, etc.).

  2. Check the Client Information Section:

    • Within the authentication service configuration, locate the ‘Client Information’ section.
    • Here, you will find the ‘Scope’ field where you can specify the scopes required for the access token.

  3. Verify the Scope in Your Request:

    • Ensure that the scope specified in your Postman request or any other client request matches the scope defined in the Pega authentication service.
    • If the ‘email’ scope is not explicitly defined in your request but appears in the access token, it might be added by default by the Pega Platform or the identity provider you are using.

  4. Adjust the Scope if Necessary:

    • If you need to add or remove scopes, you can do so in the ‘Scope’ field in the ‘Client Information’ section of the authentication service configuration.

By following these steps, you should be able to identify and configure the scopes for your access tokens. If the ‘email’ scope is being added automatically, it might be a default setting from your identity provider or a configuration in Pega that includes it by default.

Authenticating to Pega with miniOrange using OIDC protocol

OAuth 2.0 Scope support when Pega acts as the OAuth2 Provider

From external resources:*****

The “email” scope is a standard OIDC scope that is used to request the user’s email address from the identity provider.

Where is the “email” scope configured in Pega?

The “email” scope is not something that the Pega Platform adds by default. Instead, it is configured within the Authentication Service rule in your Pega application. Specifically, you will find this configuration in the OpenID Connect (OIDC) authentication service.

Here’s how you can locate the configuration:

  1. In Dev Studio, navigate to the Records Explorer.

  2. Expand the Security category and select Authentication Service.

  3. Look for the OIDC authentication service that is being used by your application.

  4. Open the authentication service rule.

  5. On the Provider tab of the authentication service ruleform, you will find a Scope field.

In this Scope field, you will likely see “email” listed, along with other standard OIDC scopes such as openid and profile. The scopes are typically separated by spaces. It is in this field that you can configure which user claims (like email, profile information, etc.) your Pega application requests from the identity provider.

Is this added by the Pega Platform?

No, the Pega Platform does not automatically add the “email” scope. It is explicitly configured in the authentication service by a developer or administrator to enable the application to retrieve the user’s email address from the identity provider. This email address is often used to map the authenticated user to an operator ID in Pega.

3

Hi @MarijeSchillern,

Many thanks for your answer.
I have checked the authentication service and it contains only “openid” as scope

Scope configuration in Authentication Service.png

So since it is returned by Pega when referring the “token”-endpoint it seems it is added by Pega by default (which is mentioned by the first AI generated answer, but contradicted by the second AI generated answer). Would this be something we can verify? Since it doesn’t appear in tracer or anything, it seems, if it is indeed added by default by Pega, that it is done somehwere deeper in Java-code or anything.
Many thanks in advance again.

Kind regards,
René

4

Hoi @Renév545, I’ll try and find out for you.

5

@Renév545

Pega didn’t invent “email” on the fly your OAuth client’s default scopes are doing it. In Dev Studio, open the OAuth 2.0 Client Registration your frontend uses (Records → Security → OAuth 2.0 → Client Registration) and check Scopes: “Default scopes” are auto-applied when the token request doesn’t send scope; remove “email” there. Also review “Allowed scopes”—if “email” is listed and set as default, Pega will include it. Next, check Records → Security → OAuth 2.0 → Scope for a scope named “email” (seeded for OIDC) and adjust or retire it if you don’t use OIDC claims. If you are using OpenID Connect, the standard OIDC scopes (openid, profile, email) may be preconfigured—remove “email” from defaults in the Client Registration. Regenerate a token after changes. Note: the app.alias. scope is injected by Pega for the application and is expected.

6

Hi @Sairohith,
Thanks for your answer. I checked it, but not sure if you are looking at a different version of Pega? We are using Pega 24.1.2.
In the Records Explorer I only have the options “Records → Security → OAuth 2.0 Client Registration” and “Records → Security → OAuth 2.0 Provider”. So we don’t have for example the option “Records → Security → OAuth 2.0 → Scope”.

Menu Records Explorer.png
Menu Records Explorer.png336×627 21.2 KB

I also checked the records of “Records → Security → OAuth 2.0 Client Registration” and couldn’t find a section to define scope in any of them. Therefore my question remains why/where is Pega adding “email” to the scope? Is this done by Pega somewhere in the background? (like the scope “app.alias.” which I understand is needed/added by Pega)

7

@TANDP is this something you could help with?

8

Hello @Renév545,

Pega Platform does not do this unless it is included in the request while making the authorize endpoint call from your front end application. When you attempt to login the frontend app, please perform the network trace and validate the query string of the authorize endpoint, the scope should contain the “email” in the request. If it does not, then could you please let me know the platform version that you are currently on so I can test this behaviour at our end.

9

Hi @Anupam Dubey,

The “email” scope does indeed originate from the client. But this is default hardcoded behavior when using the @pega/auth authentication library, which is shipped by the Pega product team. This can be verified when the out of the box WebEmbed channel is started, which loads the aforementioned library (see e.g. Dismiss - Black and search for openid+email)

The question remains why email is included hardcoded there as scope. Could you shed some light on this?

Google search seems to suggest that the “email” scope is necessary for a Pega application to access the user’s email address from a third-party identity provider. However, intercepting the authorization request and removing the “email” scope does not seem to break anything in terms of application functionality. But since it is coming hardcoded from the supplied authentication library from Pega, it can not be removed by the client.